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. Run it before a paid registry lookup rather than instead of one: a Home Affairs check is priced in rands per query, so screening structurally first means you never spend one on a number that could not have been issued. 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 you pay

API key. The free tier issues a key at /signup: send it as Authorization: Bearer <key> and calls come off a monthly allowance, no crypto anywhere in that path. Every key comes with a sandbox twin (vz_test_) that never counts against quota and accepts only the documented test inputs, so you can wire up an integration before spending a single call.

Pay per call. Send no key at all and 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. No account, no signup, which is what makes it work for autonomous agents.

Either way, invalid input is rejected with a free 400 before any payment is challenged, so you never pay (or spend quota) to learn you 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 Guides: how the interest rate caps work zaref: NCA maximum interest rates