---
title: "Create a batch of codes (max 500)"
method: POST
path: "/api/v1/codes/bulk"
tags: ["codes"]
---

# Create a batch of codes (max 500)

`POST /api/v1/codes/bulk`

## Request

- Base URL: `https://app.qrtap.kg`
- URL: `https://app.qrtap.kg/api/v1/codes/bulk`
- Auth: HTTP bearer

Creates up to 500 codes in one call. Results are per-item: one bad item does not fail the batch. Idempotent by `external_ref`, so the whole call is safe to retry.

## Request body

- CreateCodeRequest[]
  - `target_url` string, uri, required: Destination URL the code redirects to. http(s) only. Can be changed later without reprinting.
  - `label` string: Human-readable title shown in the cabinet. Defaults to "Код".
  - `external_ref` string: Your identifier for this code (partner id, SKU, event id). Unique per organization among non-archived codes; creation is idempotent by this field.
  - `group` 'partner' | 'equipment' | 'event_menu' | 'bag_insert' | 'training': Code type used to slice analytics.
  - `design_template_id` string, uuid: Apply a branded design template (must belong to your organization).

## Response `201`

Per-item results.

- object
  - `created` integer, required: Number of items with ok=true.
  - `failed` integer, required: Number of items with ok=false.
  - `data` union[], required
    - union
      - BulkItemOk
        - `ok` unknown, required
        - `id` string, uuid, required
        - `label` string, required
        - `target_url` string, nullable, required: Current destination URL.
        - `external_ref` string, nullable, required
        - `group` string, nullable, required
        - `state` string, required: Lifecycle state; API-created codes are `deployed`.
        - `design_template_id` string, uuid, nullable, required
        - `slug` string, required: Short-link slug. The QR encodes short_url = base + / + slug.
        - `short_url` string, uri, required: Stable printed link encoded in the QR. Never changes on retarget.
        - `png_url` string, uri, required: Artifact URL (PNG). Requires the same Bearer auth.
        - `svg_url` string, uri, required: Artifact URL (SVG). Requires the same Bearer auth.
        - `scans` integer: All-time non-bot scan count. Present only when listing with include=stats.
        - `created_at` string, date-time, required
        - `updated_at` string, date-time, required
      - BulkItemFailed
        - `ok` unknown, required
        - `external_ref` string, nullable, required
        - `error` string, required: Lower-cased error code, e.g. invalid_url, unknown_design_template.
  - `reused` integer, required: Сколько кодов вернулось по совпавшему external_ref вместо создания. Повторный прогон пачки даёт created=0 и reused=N.

## Other responses

- `400`: The whole payload failed validation (not an array, empty, or over 500 items).
- `401`: Missing, invalid or revoked API key.
- `402`: The capability exists but the workspace plan does not open it (bulk creation, scan webhooks, writing smart rules). Deliberately 402 and not 403: the request is valid and the identical call succeeds once the plan is upgraded — nothing in the integration has to change. Does not spend daily quota.
- `429`: Limit exceeded — the request had no effect. `error` is `rate_limited` with `scope: "minute"` (a burst brake: wait `retry_after` seconds and continue) or `quota_exceeded` with `scope: "day"` (the workspace's daily quota, counted in UTC; it returns at `reset_at`, the next UTC midnight, and only a higher plan raises it before then).

---

[API](https://skmtc.dev/qrtap/apis/qrtap-rest-api.md) · [All operations](https://skmtc.dev/qrtap/apis/qrtap-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/qrtap/apis/qrtap-rest-api/revisions/8af17ac525bd?raw)