Codes / Bulk create

Bulk create

POST/v1/codes/bulk

Creates up to 500 codes of one type in one request, as a background run you can follow — the same runs as a CSV upload in the app.

Body parameters

itemsarrayrequired1–500 codes. Each is { content, name?, slug?, folder?, fileName?, ref? }.

items[].contentobjectrequiredThe code's content; its type must equal codeType.

items[].refstringoptionalYour own reference (SKU, CRM id), echoed in the rows and the results file.

items[].folderstringoptionalA subfolder name under folderId, created when missing.

codeTypestringoptionalOne type per request. Default url.

dynamicbooleanoptionalDefault true.

folderIdstring | nulloptionalWhere the codes go. Default the workspace root.

templateIdstring | nulloptionalThe design of every code. Default the Dotwick default design.

exportobject | nulloptionalAlso render a ZIP when the run finishes, e.g. { formats: ["svg", "pdf"] }.

Example request

requestPOST /v1/codes/bulk

curl -X POST https://api.dotwick.com/v1/codes/bulk \  -H "Authorization: Bearer sk_live_…" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: fleet-2026-09-batch-3" \  -d '{    "codeType": "url",    "folderId": "fld_8k2m4q7x",    "items": [      {        "name": "Van 15",        "content": {          "type": "url",          "url": "https://example.com/fleet/van-015"        },        "ref": "VAN-015"      },      {        "name": "Van 16",        "content": {          "type": "url",          "url": "https://example.com/fleet/van-016"        },        "ref": "VAN-016"      }    ],    "export": {      "formats": [        "svg",        "pdf"      ]    }  }'

response202 Acceptedexcerpt — the run also carries its options, summary and preview rows

{  "id": "blk_9f24ab7c3e1d5f80",  "status": "queued",  "source": "api",  "codeType": "url",  "dynamic": true,  "counts": {    "total": 2,    "valid": 2,    "invalid": 0,    "created": 0,    "failed": 0,    "canceled": 0  },  "progress": 0,  "folderId": "fld_8k2m4q7x",  "exportId": null,  "createdAt": "2026-09-12T14:03:51.000Z"}

Following the run

The answer is 202 Accepted with the run. Poll GET /v1/bulk-imports/{id} until its status is succeeded, partially_succeeded or failed, then read the codes with GET /v1/bulk-imports/{id}/rows or download GET /v1/bulk-imports/{id}/results.csv. Or subscribe to bulk.completed and skip the polling.

A malformed item fails the whole request with validation_failed at items.N. Items that fail database checks (a slug already taken) are skipped and counted as invalid; the others are created. Retry the failed ones with POST /v1/bulk-imports/{id}/retry.

Limits

One code type per request: send one request per type. The plan's bulk row cap and its dynamic-code limit apply, and runs beyond the plan's concurrent jobs wait in a queue.