Skip to content
Listrar Product Data Gateway

Validate an identifier's syntax

POST
/v1/identifiers/validate
curl --request POST \
  --url https://api.listrar.com/v1/identifiers/validate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "namespace": "gtin", "value": "example" }'

Pure syntax: check digit, length, and namespace. Never touches the database and never tells you whether the product exists. namespace: "auto" infers the namespace and returns status: "ambiguous" with candidates when more than one fits.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
namespace
default: auto
Allowed values: gtin gln sscc internal_sku auto
value
required
string
<= 256 characters

Responses

Section titled “Responses”

200

Section titled “200”

The validation result, or ambiguous candidates.

Media typeapplication/json
Response envelope
object
request_id
required
string
/^req_[0-9A-HJKMNP-TV-Z]{26}$/
status
required

Typed result status. Absence (‘not_found’, ‘unknown’) is an answer carried at HTTP 200, never a 404 — see ERROR_MODEL.md design rule 1. ‘not_found’ MUST NOT be softened (06 §9).

Allowed values: found not_found unknown ambiguous partial
reason

REQUIRED when status = ‘unknown’.

Allowed values: NO_SOURCE SOURCE_UNAVAILABLE OUT_OF_SCOPE LICENCE_RESTRICTED TIMEOUT AMBIGUOUS_INPUT
data
object | null
claims
Array<object>
Claim
object
id
required
string
subject
required
string
predicate
required
string
object
required
object
value
required
unit
string | null
language
string | null
claim_type
required

INFERENCE and ESTIMATION can never be promoted to FACT. See 10 §3.

Allowed values: FACT SOURCE ASSERTION VALIDATION INFERENCE ESTIMATION UNKNOWN
method

REQUIRED for INFERENCE and ESTIMATION

string | null
method_version
string | null
source_ref
string | null
publisher_ref
string | null
evidence_refs
Array<string>
0
verification_status
Allowed values: unverified domain_verified registry_verified contract_verified disputed
verification_method
string | null
trust_level
required
Allowed values: L0 L1 L2 L3 L4 L5
confidence
number
<= 1
published_at
string | null format: date-time
retrieved_at
required
string format: date-time
superseded_by
string | null
sources
Array<object>
object
id
required
string format: uuid
kind
required
Allowed values: registry gs1_resolver publisher_endpoint partner_feed tenant_upload web
origin
required
string
operator_party_id
string | null format: uuid
trust_tier
required
integer
<= 4
robots_policy
string | null
enabled
boolean
licence_name
required
string
may_store_raw
boolean
may_redistribute_verbatim
boolean
may_redistribute_derived
boolean
attribution_required
string | null
licence_determined_by
string
licence_determined_at
string format: date-time
licence_review_due_at
string format: date-time
meta
required
object
duration_ms
required
integer
coverage

What was actually consulted, so a caller can distinguish ‘does not exist’ from ‘not covered’. Present on absence and on batch responses.

object
sources_consulted
required
Array<string>
sources_skipped
Array<object>
object
id
required
string
reason
required
Allowed values: LICENCE_RESTRICTED CIRCUIT_OPEN OUT_OF_SCOPE TIMEOUT DISABLED
next_cursor

Opaque cursor for the next page; absent means end of results. Cursor pagination only, never offset.

string
validation

Up to four independent axes, never collapsed into one verdict (12 §5). A class is absent when no rule of that class has been evaluated for this subject — which is not the same as ‘not_assessed’, a recorded verdict.

object
technical
Allowed values: pass fail warn not_assessed
business
Allowed values: pass fail warn not_assessed
regulatory
Allowed values: pass fail warn not_assessed
authority
Allowed values: none attested
warnings
Array<object>
object
code
required
string
severity
required
Allowed values: info warn error
detail
string
errors
Array<object>
Problem (RFC 9457 + extensions)
object
type
required
string format: uri
title
required
string
status
required
integer
>= 100 <= 599
code
required
string
/^[A-Z][A-Z0-9_]+$/
detail
string
<= 512 characters
request_id
string
retryable
required
boolean
docs_url
string format: uri
Example
{
  "status": "found",
  "reason": "NO_SOURCE",
  "claims": [
    {
      "subject": "gtin14:04012345678901",
      "predicate": "dpp:carbonFootprintKgCO2e",
      "claim_type": "FACT",
      "verification_status": "unverified",
      "trust_level": "L0"
    }
  ],
  "sources": [
    {
      "kind": "registry"
    }
  ],
  "meta": {
    "coverage": {
      "sources_skipped": [
        {
          "reason": "LICENCE_RESTRICTED"
        }
      ]
    }
  },
  "validation": {
    "technical": "pass",
    "business": "pass",
    "regulatory": "pass",
    "authority": "none"
  },
  "warnings": [
    {
      "severity": "info"
    }
  ]
}

Headers

Section titled “Headers”
x-request-id
string

Echoes the envelope’s request_id.

400

Section titled “400”

UNSUPPORTED_NAMESPACE

Media typeapplication/problem+json
Problem (RFC 9457 + extensions)
object
type
required
string format: uri
title
required
string
status
required
integer
>= 100 <= 599
code
required
string
/^[A-Z][A-Z0-9_]+$/
detail
string
<= 512 characters
request_id
string
retryable
required
boolean
docs_url
string format: uri
Examplegenerated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "code": "example",
  "detail": "example",
  "request_id": "example",
  "retryable": true,
  "docs_url": "https://example.com"
}

401

Section titled “401”

UNAUTHENTICATED

Media typeapplication/problem+json
Problem (RFC 9457 + extensions)
object
type
required
string format: uri
title
required
string
status
required
integer
>= 100 <= 599
code
required
string
/^[A-Z][A-Z0-9_]+$/
detail
string
<= 512 characters
request_id
string
retryable
required
boolean
docs_url
string format: uri
Examplegenerated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "code": "example",
  "detail": "example",
  "request_id": "example",
  "retryable": true,
  "docs_url": "https://example.com"
}

402

Section titled “402”

TENANT_QUOTA_EXCEEDED

Media typeapplication/problem+json
Problem (RFC 9457 + extensions)
object
type
required
string format: uri
title
required
string
status
required
integer
>= 100 <= 599
code
required
string
/^[A-Z][A-Z0-9_]+$/
detail
string
<= 512 characters
request_id
string
retryable
required
boolean
docs_url
string format: uri
Examplegenerated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "code": "example",
  "detail": "example",
  "request_id": "example",
  "retryable": true,
  "docs_url": "https://example.com"
}

429

Section titled “429”

RATE_LIMITED

Media typeapplication/problem+json
Problem (RFC 9457 + extensions)
object
type
required
string format: uri
title
required
string
status
required
integer
>= 100 <= 599
code
required
string
/^[A-Z][A-Z0-9_]+$/
detail
string
<= 512 characters
request_id
string
retryable
required
boolean
docs_url
string format: uri
Examplegenerated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "code": "example",
  "detail": "example",
  "request_id": "example",
  "retryable": true,
  "docs_url": "https://example.com"
}

500

Section titled “500”

INTERNAL_ERROR

Media typeapplication/problem+json
Problem (RFC 9457 + extensions)
object
type
required
string format: uri
title
required
string
status
required
integer
>= 100 <= 599
code
required
string
/^[A-Z][A-Z0-9_]+$/
detail
string
<= 512 characters
request_id
string
retryable
required
boolean
docs_url
string format: uri
Examplegenerated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "code": "example",
  "detail": "example",
  "request_id": "example",
  "retryable": true,
  "docs_url": "https://example.com"
}