Create batch serials via API

A batch serial groups several individual serial numbers under one batch (parent) serial number. Batch serials are created through the ERP API — send one batch serial together with all the serials that belong to it in a single request. 
 Only creating is exposed through the API. There are no API endpoints for listing, updating or deleting batch serials. 
 1. Authentication 
 All requests must be authenticated with an OAuth2 access token. Get the token by logging in with your username and password, as described in the API documentation, section OAuth2 → Login (Password Grant) . 
 The login call returns an access_token , which you send with every request: 
 Authorization: Bearer <access_token> 
 The account you log in with needs the Create batch Serial permission ( create-batch-serials ). The admin and super-admin roles have it by default. 
 2. Endpoint 
 POST https://erpapi-<tenant>.dewesoft.com/v1/batch-serials 
 Use your own company's API host — for example https://erpapi-erp.dewesoft.com/v1/batch-serials . Required headers: 
 Authorization: Bearer <access_token>
Content-Type: application/json
Accept: application/json 
 3. Request body 
 The example below creates one batch serial with two serial items: 
 {
 "serial_number": "BATCH-0001",
 "related_serials": [
 {
 "serial_1": {
 "sn": "SN-AAA-001",
 "production_date": "2026-08-17 14:12:00"
 },
 "serial_2": {
 "sn": "SN-BBB-001",
 "production_date": "2026-08-17 14:12:00"
 }
 },
 {
 "serial_1": {
 "sn": "SN-AAA-002",
 "production_date": "2026-08-18 08:30:00"
 },
 "serial_2": {
 "sn": "SN-BBB-002",
 "production_date": "2026-08-18 08:30:00"
 }
 }
 ]
} 
 If an item has only one serial number, set serial_2 to null or leave it out: 
 {
 "serial_1": { "sn": "SN-AAA-003", "production_date": "2026-08-18 09:00:00" },
 "serial_2": null
} 
 4. Fields 
 
 
 Field Required Description 
 serial_number yes Serial number of the batch (parent). Must be unique — a batch serial with the same number cannot be created twice. 
 related_serials no List of serial items that belong to this batch. Each entry is one item. 
 related_serials[].serial_1.sn yes First serial number of the item. 
 related_serials[].serial_2.sn no Second serial number (alias) of the same item. Use null when the item has only one serial number. 
 production_date no Production date of that serial, format YYYY-MM-DD HH:MM:SS . 
 
 
 production_date is kept for reference on the batch serial record only — it is not written onto the individual serial. 
 5. How serial numbers are matched 
 For every item in related_serials the system looks for an existing serial before creating a new one: 
 
 All serial numbers are converted to UPPERCASE , so lower case input is fine. 
 An existing serial is matched by its serial number or its alias, in either order — serial_1 and serial_2 can be swapped. 
 If a serial with only one number exists, the second number from the request is saved as its alias . 
 If no matching serial exists, a new one is created: serial_1 becomes the serial number and serial_2 the alias. 
 All matched and newly created serials are then linked to the batch serial. 
 
 If any of the serial numbers in the request already belongs to a lot on stock , the whole request is rejected with the message "Same serials on stock already exists. Exiting." and nothing is saved. 
 6. Trying it out 
 To send a test request, use any API client (Postman, Insomnia, or your own integration): set the method and address from step 2. Endpoint , add the three headers listed there, and paste the JSON from step 3. Request body . A successful request returns the created batch serial together with its linked serials. 
 7. Common errors 
 
 
 Message Cause 
 Unauthenticated / 401 Missing, wrong or expired access_token . 
 This action is unauthorized / 403 The user does not have the create-batch-serials permission. 
 The serial number field is required serial_number is missing from the request body. 
 Create resource failed A batch serial with this serial_number already exists. 
 Same serials on stock already exists. Exiting. One of the listed serials is already assigned to a lot on stock.