v:verza
verza / docs / kyb-api

South African KYB and onboarding API

The structural layer of a South African know-your-business or know-your-customer flow: validate an identity number, validate a VAT registration number, and screen a whole customer or supplier list in one call. Built for agents doing onboarding and compliance clean-ups rather than for a human filling in a form.

Every check states its own limits. Structural validation is not registration with Home Affairs or SARS, and verza says so on every response rather than letting a caller assume more than was checked. Invalid input is rejected free, before any payment challenge, so an agent never pays to learn it sent a typo.

Endpoints

POST /v1/bulk-validate

Validate up to 50 South African identifiers in one settled call: ID numbers, VAT numbers, or a mix. Batch screening of a customer or supplier list for structurally invalid South African identifiers, for onboarding, KYC and KYB compliance clean-ups. Same checks and same honest scope as the single endpoints, with a summary of how many passed. Cheaper than five individual ID checks and a single round trip instead of fifty.

$0.05 per call · example: /v1/bulk-validate
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}
GET /v1/vat-validate FREE

Structural validation of a South African VAT registration number (VAT vendor number): 10 digits, leading 4, check digit. Use it to screen a supplier or customer VAT number before invoicing or claiming input VAT. Free. Confirms format only, not active SARS registration.

free, no payment challenge · example: /v1/vat-validate?vat=4012345676

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 screen a list of customers?
POST /v1/bulk-validate with an ids array, a vats array, or both, up to 50 identifiers in total. One payment covers the batch, and the response includes a per-identifier result plus a summary of how many passed.
Why does a VAT-only batch get refused?
Because single VAT validation is free. Charging a batch price for work that is free per call would be selling something the caller can already have for nothing, so the endpoint refuses and points at the free route.
What does this not do?
It does not confirm registration with Home Affairs or SARS, and it does not perform sanctions, AML or fraud screening. It is the structural layer, and it is explicit about that so nobody builds a compliance process on a claim verza never made.
Do I need an account or API key?
No. Payment is the authentication. Free checks answer immediately; paid ones reply with an x402 challenge that a capable client settles in about two seconds.

Related

South African ID number validation API South African VAT number validation API NCA credit agreement lawfulness API zaref: NCA maximum interest rates