v:verza
verza / docs / id-validation-api

South African ID number validation API

A South African identity number encodes a birth date, a gender segment, a citizenship digit and a Luhn check digit. verza validates the structure and decodes those fields, returning what the number says and, just as importantly, what it does not prove.

The check is stateless. Identity numbers are never stored and never logged, which is what lets it sit inside a KYC or onboarding flow without becoming a POPIA liability of its own. Structural validity is not registration: a well-formed number that was never issued still passes, and the response says so explicitly.

Endpoints

GET /v1/id-validate

Structural validation of a South African identity number with safe decode: Luhn check digit, birth date, gender and citizenship segments (citizen or permanent resident). The structural step in KYC, KYB and customer onboarding or due diligence workflows: derive date of birth, age, gender and citizenship without storing the identity. Stateless, never stored or logged (POPIA-conscious by construction). Confirms structure only, not registration with Home Affairs.

$0.01 per call · example: /v1/id-validate?id=8001015009087 · also callable as /v1/id-validate/{id}

How agents pay

No accounts and no API keys. A paid endpoint replies HTTP 402 with the exact payment requirements; an x402 client pays USDC on Base (about two seconds to settle) and retries automatically. Invalid input is rejected with a free 400 before any payment is challenged, so an agent never pays to learn it made a typo.

Questions

How do I validate a South African ID number?
GET /v1/id-validate?id=8001015009087. It checks the Luhn check digit and the internal date segment, then returns the decoded date of birth, age, gender and citizenship status. A malformed number is rejected with a free 400 before any payment is requested.
What does the ID number actually encode?
The first six digits are the birth date (YYMMDD), the next four place the person in a gender band, the eleventh digit distinguishes a citizen from a permanent resident, and the last is a Luhn check digit over the rest.
Does a valid result mean the person exists?
No, and the response states this. Structural validation confirms the number is well formed and internally consistent. It does not confirm registration with the Department of Home Affairs, and no API that is not Home Affairs can honestly claim otherwise.
Is the identity number stored or logged?
No. The check is stateless: the number is validated in memory and never written to a log, a meter record or a database. The path-parameter form exists so the number never lands in a query string either.
Can I check a whole list at once?
Yes. POST /v1/bulk-validate takes up to 50 ID and VAT numbers in a single settled call, which is the cheaper route for onboarding clean-ups and batch screening.

Related

South African VAT number validation API NCA credit agreement lawfulness API South African KYB and onboarding API zaref: NCA maximum interest rates