Document Number Validator

Check whether a document number is well-formed for its jurisdiction, before you create a session or submit a verification. Nothing is stored and no verification is consumed.

Endpoint: POST /v1/validators/document-number
Authentication: Bearer token with the sessions scope

A stateless format check against the same registry the verification pipeline uses. Nothing is stored and no verification is consumed — but it accepts government identifiers, so it is attributed to a tenant like every other endpoint here. Useful for validating input in your own form before creating a session.

curl --request POST \
  --url https://{FQDN}/v1/validators/document-number \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "documentType": "drivers_license",
  "number": "31612967",
  "issuingCountry": "USA",
  "issuingState": "PA"
}'

{
  "documentType": "drivers_license",
  "issuingCountry": "USA",
  "issuingState": "PA",
  "valid": true,
  "rule": "drivers_license:USA:PA",
  "detail": "document number matches the PA license format"
}

The number you send is never echoed back. The response reports the jurisdiction that was applied, not the identifier you submitted.

What Is Covered

The 11 additional passport countries, as the issuingCountry you send: ARG, AUS, CHN, DEU, FRA, GBR, IND, ITA, JPN, NLD, RUS.

Anything not marked ✓ — inside the table or beyond it — returns valid: null, never false. Treat a null as "we do not know": accept it, and do not read it as either a pass or a fail.

The CNH, CPF and DNI/NIE are checked with real check-digit arithmetic, so a transposed digit is caught — unlike the licence tables, which are shape-only because those jurisdictions publish no check digit.

Naming the Jurisdiction

issuingCountry is the country — an ISO 3166-1 alpha-3 code, a country name, or a common alias. issuingState is a subdivision within that country — a US state or a Canadian province or territory — and only driver's licenses use it.

A licence must name its country. A subdivision cannot: send issuingState without issuingCountry and the request is refused, because PA alone could be Pennsylvania or Pará and the answer would name a jurisdiction you never supplied. Sending neither is allowed and returns valid: null — unverifiable, not invalid. Nothing infers a country: a passport or identity card without one also returns valid: null.

ssn and itin are validator-only. They are not capturable document types — you cannot create a session for one — but the structural rules are useful when you collect them on your own forms.

Interpreting the Response

valid is deliberately three-valued:

A null is the honest answer for a jurisdiction we have no rule for, and it is the reason coverage gaps below are safe rather than silently wrong.

rule names the rule that was applied, so you can tell which jurisdiction answered:

Every rule names the documentType it belongs to, so the prefix maps to the type by string equality. The one exception is a sandbox reserved value, which is prefixed reserved: and carries the type in its second segment — see Sandbox and Test Data.

Errors

Next Steps

• Verification Sessions — creating a session, and the prefill that uses this same check
• Sandbox & Test Data — reserved numbers that return a chosen verdict on demand