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. A jurisdiction that is marked ✓ also answers null when the number matches none of the shapes we hold for it — see the verdict table below.

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 subdivision must name its country. Send issuingState without issuingCountry and the request is refused whatever the document type, because PA alone could be Pennsylvania or Pará and the answer would name a jurisdiction you never supplied. ssn and itin are exempt — their country is never in doubt. 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 false needs a proof. The CNH, CPF, DNI/NIE, SSN and ITIN carry one, and a value that no jurisdiction could issue — punctuation in a licence number, a shape outside the generic ICAO one for a passport — is refuted on its face.

A licence or passport number that simply matches none of the shapes we hold for its jurisdiction returns null, not false. Those tables recognise shapes; they do not verify them, and they are incomplete in ways real documents keep finding. Maryland issues an MD-prefixed number alongside its legacy one, and Massachusetts a two-letter prefix; each was missing until a genuine licence was rejected by it. Answering false there told a caller a valid document was invalid.

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