Skip to main content
POST
Author a recall scope

Authorizations

X-API-Key
string
header
required

Path Parameters

organization_id
string<shortuuid>
required

Identifier of the organization.

Required string length: 22
Pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$
recall_id
string<shortuuid>
required

Identifier of the recall.

Required string length: 22
Pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$
gtin
string<gtin>
required

GTIN of your affected product.

Required string length: 8 - 14
Pattern: ^[0-9]{8}$|^[0-9]{12,14}$

Body

application/json

The same scope body, with the per-kind rules checked by the route instead of at parse time.

The kind-dependent rules (a value list for a lot scope, a GLN check digit, a window that ends after it starts) cannot be written in the published JSON Schema, so a body that satisfies the schema can still fail them. Checking at parse time would answer 422 before the route has resolved the organization, the recall and the caller's role; the rules are applied after those checks, so a caller is told about a recall they cannot see (404) or a role they lack (403) before being told their body is malformed.

kind
enum<string>
required

Which predicate this scope is. Determines whether values or the date fields apply.

Available options:
LOT_LIST,
SERIAL_SET,
PRODUCTION_SITE,
DATE_WINDOW
values
string[]

For LOT_LIST / SERIAL_SET / PRODUCTION_SITE: the recalled lot (AI 10), serial (AI 21) or production-site GLN (AI 416) values. A PRODUCTION_SITE value must be a 13-digit GLN with a valid check digit. Matched exactly and case-sensitively (GS1 CSET 82); surrounding whitespace is trimmed and duplicates are dropped. At least one value is required for these kinds; the maximum list size is server-configured (see RECALL_SCOPE_MAX_VALUES). Ignored for DATE_WINDOW.

Maximum array length: 10000
Pattern: ^[^\x00]{0,}$
date_ai
enum<string> | null

For DATE_WINDOW: which printed date AI the window applies to (15 or 17). Required for that kind.

Available options:
15,
17
start
string<date> | null

For DATE_WINDOW: inclusive start of the affected printed-date range (YYYY-MM-DD). Required for that kind.

end
string<date> | null

For DATE_WINDOW: inclusive end of the affected printed-date range (YYYY-MM-DD). Must be >= start. Required for that kind.

Response

Created

A scope on a recall for one of your products, confirmed or suggested.

id
string<shortuuid>
required

URL-safe 22-character shortuuid encoding of the row's UUID primary key. Stable across the row's lifetime; suitable for sharing in URLs, log lines, and external SDK clients. Accepted on input as either the shortuuid form or the canonical UUID form (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).

Required string length: 22
Pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$
kind
string
required

DATE_WINDOW, LOT_LIST, SERIAL_SET or PRODUCTION_SITE.

status
string
required

CONFIRMED scopes narrow the live recall verdict. SUGGESTED is a regulator-fed draft that narrows nothing until you confirm it.

is_active
boolean
required

False once deactivated or dismissed; kept for audit, never deleted.

values
string[]
required

Lot, serial or production-site GLN values; empty for a date window.

date_ai
string
required

Printed-date AI (15 or 17) of a date window; empty otherwise.

note
string
required

Free-text note on the scope.

pack_date_start
string<date> | null

Inclusive start of a date window.

pack_date_end
string<date> | null

Inclusive end of a date window.

confidence_score
number | null

Extraction confidence from 0.0 to 1.0 for a suggestion; null for a scope you authored.