Declare GS1 company prefix claim(s) (verification required)

POST 
/api/v1/companies/me/gs1-prefixes

Declares GS1 company prefix claims for your company. Each claim stays pending until Traceable verifies it against your GS1 licence.

Required scope: dpp:draft:write. A WRITE (HMAC + Idempotency-Key). ADD semantics — the provided prefixes are merged into your company's ACTIVE claim set (deduped). Each prefix must be 6-12 digits.

A POSTed prefix lands as a Declared claim awaiting verification — it does NOT close the publish gate. Traceable reviews each claim against your GS1 licence certificate; the licence artefact upload is available in the operator UI only (Company Profile → GS1 Prefixes), by design. Until a claim is verified, the gate reports gs1_prefix_pending_verification; prefixes in every response stays verified-only, with claim statuses in registrations.

Request

Responses

201

Claim(s) declared (verification pending)

400

400 — INVALID_JSON, VALIDATION_ERROR, VALIDATION (the {id} path segment is not a UUID), or IDEMPOTENCY_KEY_REQUIRED.

401

401 — INVALID_SIGNATURE or SIGNING_NOT_CONFIGURED (or bearer auth failure).

403

403 — missing scope (FORBIDDEN_SCOPE) or module (FORBIDDEN_MODULE).

422

A prefix is not 6-12 digits, or the claim limit is reached (GS1_PREFIX_INVALID).

429

429 — RATE_LIMITED (per-key limit, reads and writes alike; fails closed, so a limiter outage also returns 429). A limiter-down 429 is deliberately indistinguishable from a quota 429. Carries Retry-After (seconds).

Response Headers

Retry-After

Seconds to wait before retrying (429 only).

RateLimit-Limit

Per-minute request ceiling for this key's tier.

RateLimit-Remaining

Requests left in the current window (floored at 0).

RateLimit-Reset

Seconds until the window resets.

503

503 — the API is not enabled on this environment (FEATURE_DISABLED).