Loading API Documentation...
Loading API Documentation...
Last updated
South Africa's identity verification and compliance API. Verify IDs, screen for AML/PEP, and more.
Instant verification from Home Affairs and approved data sources
Built for South African regulatory requirements
Simple JSON API with comprehensive documentation
https://www.verifynow.co.za/api/externalAll API requests require an API key passed in the x-api-key header.
curl -X POST https://www.verifynow.co.za/api/external/verify \
-H "x-api-key: vn_live_abc123..." \
-H "Content-Type: application/json"Never expose your API key in client-side code. Make API calls from your server only.
The VerifyNow REST API lets South African businesses run identity verification, refugee and asylum identity checks, AML/PEP screening, CIPC checks, bank account verification, face match, and vehicle lookup from their own application. Protected routes use the x-api-key header; responses are JSON and follow the schema documented for each endpoint.
Driver's Licence Verification and the Vehicle Licence Disc Scanner are available as dashboard betas for photo and camera scans. Both scanners are available through additive public API endpoints.
API requests use the full path shown below on https://www.verifynow.co.za. For a service overview, visit Passive Liveness or iGaming verification. See System Status for service availability.
API calls are billed via credits. Purchase upfront and they are deducted per successful verification.
curl -X GET https://www.verifynow.co.za/api/external/my_credits \
-H "x-api-key: vn_live_abc123..."Volume-based pricing with discounts for higher API call volumes. The more you verify, the more you save.
Tier discounts are built in. The credit pack you choose on the Buy Credits page determines its effective per-credit price. Volume discounts are available to enterprise clients. Contact Enterprise Sales for a volume-based quotation.
View credit tiersCurrency amounts below and in endpoint price cards are illustrative standard-rate examples. USD amounts are approximate. Your credit pack or assigned enterprise rate determines the effective cost; see current pricing.
| Category | Description | Per Credit (ZAR) | Per Credit (USD) |
|---|---|---|---|
| Standard | Pay-as-you-go | R2.99 | $0.18 |
| High Volume / Enterprise | Custom volume-based pricing | Contact Enterprise Sales → | |
Industry workflow pricing
These are verification paths, not credit-purchase tiers. Choose an industry from the header to open its guide.
Basic
Uses the core verification calls for the normal customer journey. The guide lists those calls and their endpoint pricing.
Step-up
Starts with Basic, then adds only the checks triggered by risk, a mismatch, a payout or another defined event.
Exchange Rate: Prices in USD calculated at ZAR 17 : $1. All prices are per credit.
Pre-paid Model: Purchase credits upfront and use them as needed. No monthly minimums or hidden fees.
Credit Usage: Each endpoint shows its credit cost. See /pricing for current pricing.
Operational guidanceThere is no published universal requests-per-minute tier or concurrency allowance per API key. Production capacity depends on the endpoint and account agreement. Confirm expected peak traffic and concurrency with support before launch; these docs do not promise unlimited requests.
The two-second repeated-payload cooldown on the verification sandbox applies to the same IP, endpoint and identifier. That sandbox cooldown does not apply to production verification requests. Service-specific controls still apply.
SMS OTP defaults are 100 sends, 300 verification requests and 300 status polls per minute per account scope. An organization shares that scope across its keys; a personal account has its own scope. Limits can be adjusted for an account. Each phone allows one send per 60 seconds, five per hour and ten per rolling 24 hours. Each challenge allows 30 verification requests and 12 status polls per minute. See /api-docs#sms-otp for the full rules.
When an endpoint returns 429 with Retry-After, wait for that interval. Retrying a pending production operation must preserve its Idempotency-Key and payload.
HTTP 429 Retry-After: <seconds until retry>
GET /api/external/receipts?service={service}&reference={reference}Use x-api-key from the original request. Set reference to its original Idempotency-Key (1–128 characters) and service to a supported value below. This read-only request uses zero credits and requires no Idempotency-Key header.
Supported service values: id-enhanced, africa-verification, aml-screening, cipc, cipc_director_search, bank-account-verification, property-search, vehicle-check, address-lookup, facematch, proof-of-address, age-estimate, passive-liveness, id-document-verify, drivers-licence, smart-id-card, vehicle-licence-disc, refugee-verification, home_affairs_id_photo, said_verification, home_affairs_real_time_idv, marital-status-real-time, kyc_bundle, employee_bundle, consumer_trace, contact_enquiry.
HTTP 200 returns status: completed with result, status: failed with error and responseStatus, or status: pending. A pending Africa verification job can include jobId. A charged no-record outcome is returned as completed with its saved result.
HTTP 410 means the saved receipt is unavailable. Review the original request before starting another paid check. Invalid parameters return 400; authentication failures return 401. The limit is 60 requests per minute per user, with 429 when exceeded. Recovery never submits another verification request.
curl --get https://www.verifynow.co.za/api/external/receipts \ -H "x-api-key: YOUR_ORIGINAL_API_KEY" \ --data-urlencode "service=said_verification" \ --data-urlencode "reference=original-request-key"
POST /api/external/aml-monitoringAn approved organization API key and an active AML monitoring licence are required in sandbox and production. Send x-api-key and Content-Type: application/json. Production requires an Idempotency-Key of 8–160 characters. This licensed screening endpoint uses zero wallet credits; licence and population limits apply.
Required JSON fields: name (2–300 characters), entity (integer 0–7), country (2-letter ISO code), dataset (sanctions or default), and mode (sandbox or production). Entity values: 0 Person, 1 Company, 2 Organization, 3 LegalEntity, 4 Vessel, 5 Airplane, 6 Security, 7 CryptoWallet.
Optional categories accepts sanctions, pep, rca, crime, wanted, regulatory, debarment and adverse_media. The sanctions dataset allows only sanctions. Omitted categories use the defaults for the dataset and licence tier. PEP, RCA and adverse_media require the active full financial-crime data licence; adverse_media also requires active adverse-media access.
Optional properties maps supported keys to arrays of strings: alias, firstName, middleName, lastName, birthDate, country, nationality, citizenship, idNumber, passportNumber, registrationNumber, taxNumber, vatCode, leiCode, isin, figiCode, address, jurisdiction, imoNumber, mmsi, callSign, flag, serialNumber, model, publicKey, currency and identifier. Each key accepts up to 20 values; the request allows 60 values total, each 1–500 characters after trimming.
HTTP 200 includes success, requestId, results, remainingCredits, screened_name, screened_entity_type, screened_country and screened_dataset. Results include Header, SearchResults and PossibleMatches. Header supplies dataset and audit references. Additional fields may be present; ignore unknown keys.
Reuse the same key and payload to recover the existing screen. A pending request returns 202 with requestId and auditReference; changing the payload returns 409. Input errors return 400, authentication failures 401, and licence or access failures 403. Rate limits return 429 with Retry-After. Screening failures can return 409 or 503. Follow the returned retry guidance.
Your application initiates each screen. For subject enrolment, rescreening and withdrawal, use the ongoing AML workflow at /api-docs/verifynow-aml.
curl -X POST https://www.verifynow.co.za/api/external/aml-monitoring \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: monitoring-example-0001" \
-d '{"name":"Alex Morgan","entity":0,"country":"za","dataset":"sanctions","mode":"sandbox","categories":["sanctions"]}'Production verification submissions require an Idempotency-Key header to prevent duplicate operations. This ensures that retrying a request (e.g., due to network issues) won't result in double-charging credits. GET receipt and job-status requests, and POST webhook retries, do not require this header. Follow each endpoint’s requirements.
Idempotency-Key header is requiredIdempotency-Key header is optionalcurl -X POST https://www.verifynow.co.za/api/external/verify \
-H "x-api-key: vn_live_abc123..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-d '{"reportType": "said_verification", "idNumber": "8001015009087", "mode": "production"}'Use a UUID (v4) for each unique operation. Store it with your request so you can safely retry if needed. Never reuse an idempotency key for a different request.
Sandbox-only. Production behaviour is unchanged and sandbox calls still cost 0 credits. Use these reserved inputs after normal request validation to force a completed negative or a could-not-complete error. Repeating the same sandbox payload from the same IP returns 429 after a 2-second cooldown. Distinct reserved inputs (pass / 90 / 91) are not locked by each other. Playground, Postman, and curl share this lock.
| Service | Trigger | Examples |
|---|---|---|
| SA ID and other /verify ID reports | Valid 13-digit ID ending 90 or 91 | 8001010000990 / 8001010000891 |
| CIPC company / director | Identifier digits ending 90 or 91 | 000000000090 / 000000000091 |
| Bank account verification | identityNumber or bankAccountNumber digits ending 90 or 91 | 8001010000990 or 123456790 |
| AML one-shot and ongoing | name ending 90 or 91. Ongoing sandbox still returns DatasetVersion on a clear result | Sandbox Negative 90 / Sandbox Error 91 |
| Contact enquiry | contactNumber ending 90 or 91 | 0821234590 / 0821234591 |
| Number Plate Lookup | registrationNumber digits ending 90 (no record, 404), 91 (unavailable, 503) or 92 (vehicle without specifications) | DEMO190GP / DEMO191GP / DEMO192GP |
| Vehicle Valuation estimate | mileageKm ending 90 (no valuation, 422) or 91 (error, 502) | 85090 / 85091 |
| Face match | id_number last two digits 00–09, 36–45 or 72–81 → In Review; 90 → Declined; 91 → error | 8001010000990 / 8001010000891 |
| Passive liveness, age estimate, ID document, licence scanners | Valid image whose image_base64 (or front file) length mod 100 is 0–4 (Declined), 5–19 (In Review), or 90–94 (error) | Pad a real sample image so length % 100 lands in the band |
For South African ID inputs, we recommend running the standard ID checksum in your application before sending a verification request. This optional pre-flight validation catches typing errors early and can help avoid unnecessary calls. It does not change endpoint paths, payload fields, or response formats.
Request composition
VerifyNow does not accept an arbitrary array of checks in one public API request. Use a supported bundle where one exists. For a custom combination, expose one endpoint from your server and let that endpoint coordinate the required VerifyNow calls.
Use bundle: "facematch_verified" on POST /facematch. It combines basic SA ID verification with a selfie-to-reference-image comparison in one VerifyNow call. It does not fetch a Home Affairs photo.
Use bundle: "facematch" on POST /facematch. It obtains the supported Home Affairs reference photo and compares the submitted selfie in one VerifyNow call.
Bank Account Verification cannot currently be added to either Face Match bundle payload. It remains a separate VerifyNow request, with its own idempotency key and normal component charge.
Your frontend or partner calls one endpoint that you control. Your server keeps the API key private, runs the appropriate Face Match bundle and Bank Verification, then returns one combined response.
POST /api/verification/combined
{
"mode": "production",
"idNumber": "8001015009087",
"firstName": "Jane",
"surname": "Doe",
"selfieImageBase64": "data:image/jpeg;base64,...",
"referenceImageBase64": "data:image/jpeg;base64,...",
"bank": {
"name": "Example Bank",
"accountNumber": "1234567890",
"branchCode": "250655",
"accountType": "Cheque"
}
}const VERIFYNOW_API = 'https://www.verifynow.co.za/api/external';
async function callVerifyNow(path, body, idempotencyKey) {
const response = await fetch(`${VERIFYNOW_API}${path}`, {
method: 'POST',
headers: {
'x-api-key': process.env.VERIFYNOW_API_KEY,
'Content-Type': 'application/json',
'Idempotency-Key': idempotencyKey,
},
body: JSON.stringify(body),
});
const data = await response.json();
if (!response.ok) throw new Error(data.error || 'Verification failed');
return data;
}
export async function runCombinedVerification(input, requestId) {
const useSuppliedReference = Boolean(input.referenceImageBase64);
const identityAndFace = callVerifyNow(
'/facematch',
useSuppliedReference
? {
bundle: 'facematch_verified',
mode: input.mode,
id_number: input.idNumber,
selfie_image_base64: input.selfieImageBase64,
reference_image_base64: input.referenceImageBase64,
}
: {
bundle: 'facematch',
mode: input.mode,
id_number: input.idNumber,
selfie_image_base64: input.selfieImageBase64,
},
`${requestId}:identity-face`
);
const bank = callVerifyNow(
'/bank-account-verification',
{
type: 'Individual',
firstName: input.firstName,
surname: input.surname,
identityNumber: input.idNumber,
identityType: 'IDNumber',
bankName: input.bank.name,
bankAccountNumber: input.bank.accountNumber,
bankBranchCode: input.bank.branchCode,
bankAccountType: input.bank.accountType,
mode: input.mode,
},
`${requestId}:bank`
);
const [identityFaceResult, bankResult] = await Promise.all([
identityAndFace,
bank,
]);
return {
requestId,
checks: {
identityFace: identityFaceResult,
bank: bankResult,
},
};
}The example runs both checks in parallel because both are required. If Bank Verification is a step-up check, run it only after the identity and face result passes your policy so an unnecessary second call is not made.
reportTypeRequiredidNumberRequiredmodeRequired| Name | Type | Required | Description |
|---|---|---|---|
| reportType | string | Required | "home_affairs_id_photo" |
| idNumber | string | Required | 13-digit SA ID number |
| mode | string | Required | "sandbox" (test) or "production" (live, uses credits) |
curl -X POST https://www.verifynow.co.za/api/external/verify \
-H "x-api-key: vn_live_abc123..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: unique-request-id" \
-d '{
"reportType": "home_affairs_id_photo",
"idNumber": "8001015009087",
"mode": "production"
}'The example shows normalized fields. Additional fields and availability vary by response path. PhotoAvailable and PhotoStatus describe the returned Photo value. Treat transaction_id as an opaque reference.
Note: Production API responses provide more comprehensive data.
reportTypeRequiredidNumberRequiredmodeRequired| Name | Type | Required | Description |
|---|---|---|---|
| reportType | string | Required | "said_verification" |
| idNumber | string | Required | 13-digit SA ID number |
| mode | string | Required | "sandbox" (test) or "production" (live, uses credits) |
curl -X POST https://www.verifynow.co.za/api/external/verify \
-H "x-api-key: vn_live_abc123..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: unique-request-id" \
-d '{
"reportType": "said_verification",
"idNumber": "8001015009087",
"mode": "production"
}'Fields depend on the verification source and available record. Names, Surname, IDValid, DeceasedStatus, DateOfDeath and IdentityType appear under realTimeResults.Verification where available; TransactionID appears under realTimeResults. Additional fields may be present; ignore unknown keys.
Note: Production API responses provide more comprehensive data.
Real-time alive/death verification includes deceased status information where returned by the source. Use this deceased status API check when your workflow needs to establish whether a South African ID record is marked alive or deceased.
reportTypeRequiredidNumberRequiredmodeRequired| Name | Type | Required | Description |
|---|---|---|---|
| reportType | string | Required | "home_affairs_real_time_idv" |
| idNumber | string | Required | 13-digit SA ID number |
| mode | string | Required | "sandbox" (test) or "production" (live, uses credits) |
curl -X POST https://www.verifynow.co.za/api/external/verify \
-H "x-api-key: vn_live_abc123..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: unique-request-id" \
-d '{
"reportType": "home_affairs_real_time_idv",
"idNumber": "7905011111118",
"mode": "production"
}'Note: Production API responses provide more comprehensive data.
include_photoOptionalrefugeeFileNumberRequiredauthority_confirmedRequiredmodeRequired| Name | Type | Required | Description |
|---|---|---|---|
| include_photo | boolean | Optional | Defaults to true. Set false to omit the photo from the response; upstream retrieval and processing remain unchanged. |
| refugeeFileNumber | string | Required | NIIS file number as a non-empty string. Example: ABC00123456 or ABC/001234/56. Examples are not format requirements. |
| authority_confirmed | boolean | Required | Must be true after confirming lawful authority to process the identity information |
| mode | string | Required | "sandbox" or "production" |
curl -X POST https://www.verifynow.co.za/api/external/refugee-verification \
-H "x-api-key: vn_live_abc123..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: unique-request-id" \
-d '{
"refugeeFileNumber": "ABCDEF000000000",
"authority_confirmed": true,
"mode": "production"
}'Note: Production API responses provide more comprehensive data.
Essential tools for FICA compliance, AML screening, and bank account verification.
nameRequiredentityRequiredmodeRequiredcountryOptional| Name | Type | Required | Description |
|---|---|---|---|
| name | string | Required | 2–200 characters. Person searches require first name and surname. |
| entity | integer | Required | 0 Person or 1 Company |
| mode | string | Required | sandbox or production |
| country | string | Optional | 2-letter ISO code for the included AML/PEP screening (results.amlScreening, same layout as /aml-screening results). Defaults to "za". Included in the price; if it cannot run, the request returns 503 uncharged. |
curl -X POST https://www.verifynow.co.za/api/external/adverse-media -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" -H "Idempotency-Key: adverse-example-0001" -d '{"name":"Jane Example 90","entity":0,"mode":"sandbox"}'The request and response above show the zero-credit sandbox no-findings scenario.
This fictional article shows the response shape. The excerpt omits other response fields, including amlScreening. The price is loaded from the pricing table; when unavailable, the placeholder below is documentation text.
curl -X POST https://www.verifynow.co.za/api/external/adverse-media \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: adverse-production-example-0001" \
-d '{"name":"Alex Morgan","entity":0,"country":"za","mode":"production"}'Production requires an Idempotency-Key of 8–160 characters. Reuse the key with the same payload to replay a result for up to 48 hours without another charge. Saved responses are encrypted. A pending request returns 202 with Retry-After; a changed payload returns 409.
Sandbox uses zero credits: names ending in 90 return no findings, 91 returns a simulated 502, and other names return a labelled synthetic article. Allow two seconds between sandbox calls.
Article evidence includes available titles, publication dates, source links and confidence scores. Additional premium screening findings appear in screening; this field can be null. A score does not prove identity or wrongdoing.
400 means invalid input, 401 invalid credentials, 402 insufficient credits, 429 sandbox cooldown, and 502/503 an unavailable service. A billing review response includes requestId for support. Refunds require human review. Country and threshold filters are not supported.
Note: Production API responses provide more comprehensive data.
modeRequirednameRequiredentityRequiredcountryRequireddatasetRequiredidNumberOptionalpassportNumberOptionalregistrationNumberOptionaldateOfBirthOptionalrefineWithDobOptional| Name | Type | Required | Description |
|---|---|---|---|
| mode | string | Required | "sandbox" or "production" |
| name | string | Required | Full name or business name to screen |
| entity | integer | Required | Entity type: 0=Person, 1=Company, 2=Organization, 3=LegalEntity |
| country | string | Required | 2-letter ISO country code (e.g., "za", "us", "gb") |
| dataset | string | Required | Accepted for compatibility: "all", "sanctions", "peps", or "crime". Every value returns the complete sanctions, PEP, and crime screening result. |
| idNumber | string | Optional | Optional SA ID number. An exact match on a list raises the score. With country "za" and refineWithDob it also supplies the date of birth. |
| passportNumber | string | Optional | Optional passport number. An exact match on a list raises the score. |
| registrationNumber | string | Optional | Optional company registration number. An exact match on a list raises the score. |
| dateOfBirth | string | Optional | Optional YYYY-MM-DD date of birth for a person. Used when date-of-birth refinement applies. |
| refineWithDob | boolean | Optional | Lowers the score of listed people whose date of birth differs. Depending on your account, refinement may be on by default whenever dateOfBirth or an SA ID is sent. Send true or false to choose explicitly. Automatic refinement adds results.Header.DobRefinement ("applied" or "not_applied"). |
curl -X POST https://www.verifynow.co.za/api/external/aml-screening \
-H "x-api-key: vn_live_abc123..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: unique-request-id" \
-d '{
"mode": "production",
"name": "John Doe",
"entity": 0,
"country": "za",
"dataset": "all"
}'A failed first attempt can return HTTP 409 when its key is replayed. Follow the returned guidance and use a new key for a replacement request. match is a legacy field; read Header, SearchResults and PossibleMatches for the screening result.
Note: Production API responses provide more comprehensive data.
ConfidenceScore and score use the same 0–1 evidence scale: an exact name alone scores 0.50; an exact name with a matching full DOB scores 1.00; an exact name with a matching identifier can reach 1.00. A matching partial birth date contributes 0.10. Contradictory birth dates or numbers in names reduce the score. Country and address signals support candidate selection. The maximum score describes evidence agreement and requires identity review. Candidate retrieval still uses its existing threshold, shown in SearchResults.InputMinScore, so a returned match can have ConfidenceScore below 0.90. MatchExplanations contains the contributing signals; FieldEvidence identifies their sources. Existing response fields and request parameters are unchanged. Previously saved or idempotently replayed responses retain their recorded scores. This applies to /aml-screening and /aml-ongoing.
| Key | Effect on score | Meaning |
|---|---|---|
name_match | Up to 0.50 | Best similarity between the submitted name and the listed name or its aliases. Every match has it. |
identifier_match | +0.50 | An ID, passport, registration, LEI or tax number matches after format normalization. Together with an exact name match this reaches the maximum score, subject to contradictory evidence. |
birth_date_match | +0.50 | The date of birth you sent (or the one taken from an SA ID) matches a listed date. |
birth_date_partial_match | +0.10 | With refineWithDob, the known parts of the date agree but the listed date is less precise. |
birth_date_mismatch | −0.20 | With refineWithDob, the known parts of the date disagree. An exact identifier match is still returned for review. |
birth_year_match | +0.10 | Without refinement, the birth year agrees but the full date differs in precision. |
birth_year_mismatch | −0.20 | Without refinement, the supplied and listed birth years differ. |
country_match | Candidate selection only | The country you sent agrees with the listed country. |
country_mismatch | Candidate selection only | The country you sent differs from the listed country. |
address_match | Candidate selection only | An address you sent is similar to a listed address. |
name_number_mismatch | −0.15 | Numbers in the submitted and listed names differ, for example vessel or company numbers. |
"ConfidenceScore": 1.00,
"MatchExplanations": {
"name_match": { "score": 1, "weight": 0.5, "impact": 0.5,
"query": "atul gupta", "candidate": "atul gupta",
"detail": "Best comparison across the submitted name and source aliases." },
"birth_date_match": { "score": 1, "weight": 0.5, "impact": 0.5,
"query": "1968-06-14", "candidate": "14 Jun 1968",
"detail": "A supplied or ID-derived date of birth matches a source value." },
"country_mismatch": { "score": 1, "weight": 0, "impact": 0,
"query": "south africa", "candidate": "united arab emirates",
"detail": "The supplied and listed countries differ. This signal supports candidate selection." }
}operation: onboarding is the first screen and ongoing is a same-subject rescreen on an active licence. The first enrol uses the same credits as the one-shot screen. A licensed rescreen uses 0 credits. Production and sandbox responses include results.Header.DatasetVersion and results.Header.DatasetPublishedAt. Sandbox uses the sample version aml_20260817_sample. results.Header.ScreenedAt is the time of that screen. Withdrawal and the dataset webhook are on the VerifyNow AML guide. For reseller integrations using ongoing AML, see Using ongoing AML in your own platform. Buy an ongoing AML licence and add credits for your initial enrolments in the dashboard.modeRequirednameRequiredidentifierTypeRequiredidentifierValueRequiredidentifierCountryOptionalpropertiesOptionalentityRequiredcountryRequireddatasetRequireddateOfBirthOptionalrefineWithDobOptional| Name | Type | Required | Description |
|---|---|---|---|
| mode | string | Required | "sandbox" or "production" |
| name | string | Required | Person or company name, 2 to 300 characters |
| identifierType | string | Required | sa_id, national_id or passport for a person; cipc, company_registration, lei or tax for a company. customer_reference accepts a unique numeric enrolment reference for either. |
| identifierValue | string | Required | The ID, passport, CIPC, LEI, or tax number |
| identifierCountry | string | Optional | Required for national_id, passport, company_registration and lei. Use the two-letter issuing country or registry jurisdiction. SA identifiers default to ZA; omit for customer_reference. |
| properties | object | Optional | Supported screening properties mapped to arrays of strings. Maximum 20 values per key, 60 total, 500 characters per value. See the ongoing AML guide for supported keys. |
| entity | integer | Required | Entity type: 0=Person, 1=Company, 2=Organization, 3=LegalEntity |
| country | string | Required | 2-letter ISO country code (e.g., "za", "us", "gb") |
| dataset | string | Required | "all", "sanctions", "peps", or "crime" |
| dateOfBirth | string | Optional | Optional YYYY-MM-DD date of birth for a person. With identifierType "sa_id" the date comes from the ID. |
| refineWithDob | boolean | Optional | Lowers the score of listed people whose date of birth differs. Depending on your account, refinement may be on by default whenever dateOfBirth or an SA ID is sent. Send true or false to choose explicitly. The default also applies to every rescreen. |
curl -X POST https://www.verifynow.co.za/api/external/aml-ongoing \
-H "x-api-key: vn_live_abc123..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: unique-request-id" \
-d '{
"mode": "production",
"name": "Jane Doe",
"entity": 0,
"country": "za",
"dataset": "all",
"identifierType": "sa_id",
"identifierValue": "8001015009087"
}'Set x-verifynow-rescreen-only: 1 to require an existing active enrolment and matching name, preventing a new onboarding operation. Error identifiers can be returned in error rather than code. Read the HTTP status and endpoint response. The list covers screening and withdrawal; some failures use a message without a machine-readable identifier.
| HTTP / error | Handling |
|---|---|
| 401 | Missing, invalid or unsupported API key. A recognised key without licence access returns 403. |
| 400 | Invalid body, entity, dataset or properties. Idempotency-Key must be between 8 and 160 characters for production screening; withdrawal requires the header. Sandbox screening does not require it. |
| 400 MISSING_IDENTIFIER_TYPE / MISSING_IDENTIFIER_VALUE | Supply the required identifier fields. |
| 400 INVALID_IDENTIFIER / INVALID_IDENTIFIER_TYPE / INVALID_IDENTIFIER_COUNTRY | Correct the identifier format, type and country for this entity. |
| 400 INVALID_ENTITY | Withdrawal accepts entity 0, 1, 2 or 3. |
| 402 INSUFFICIENT_CREDITS | The onboarding operation cannot cover its required credits. |
| 403 Active AML monitoring licence required | The key is recognised, but production licence access is unavailable. |
| 403 ORGANIZATION_INACTIVE | The organization is inactive. |
| 403 AML_LICENCE_REQUIRED / AML_LICENCE_SUSPENDED / AML_LICENCE_REVOKED / AML_LICENCE_EXPIRED | Resolve the licence status before screening. |
| 403 AML_DATA_PLATFORM_SUSPENDED | Licensed data access is suspended. |
| 403 POPULATION_LIMIT_EXCEEDED | The licensed active population limit has been reached. |
| 403 FULL_FINANCIAL_CRIME_REQUIRED | The licence lacks the requested financial-crime coverage. |
| 404 SUBJECT_NOT_FOUND | Withdrawal could not find the identified subject. |
| 409 SUBJECT_NOT_ACTIVE | The withdrawal subject is already inactive. |
| 409 IDEMPOTENCY_PAYLOAD_CONFLICT | The key was reused with a different payload or operation. |
| 409 AML_SUBJECT_NOT_ENROLLED | Rescreen-only requests require an active enrolment and matching name. |
| 409 IDEMPOTENCY_EXPIRED / IDEMPOTENCY_FAILED | Retry the operation with a new key as directed by the error. |
| 409 OPERATION_FENCE_MISMATCH | The operation state changed; reconcile the saved outcome before starting a new request. |
| 409 / 503 AML_ONGOING_UNAVAILABLE | Screening is unavailable or a service conflict occurred. Follow the returned guidance. |
| 503 AML_SUBJECT_KEY_UNAVAILABLE | The subject-key service is unavailable. |
| 503 AML_REPLAY_UNAVAILABLE | The saved response could not be opened. Contact support before starting a replacement enquiry. |
| 429 RATE_LIMITED | Wait for Retry-After. |
| 202 pending | An operation for that key is still in progress. Retry after Retry-After. |
Note: Production API responses provide more comprehensive data.
typeOptionalfirstNameOptionalsurnameRequiredidentityNumberRequiredidentityTypeRequiredbankAccountNumberRequiredbankBranchCodeRequiredbankNameOptionalbankAccountTypeRequiredmodeRequired| Name | Type | Required | Description |
|---|---|---|---|
| type | string | Optional | "Individual" (default) or "Company" |
| firstName | string | Optional | First name (Individual) or empty (Company) |
| surname | string | Required | Surname (Individual) or Company Name (Company) |
| identityNumber | string | Required | SA ID, temporary ID, company or trust registration number |
| identityType | string | Required | "IDNumber", "TemporaryIDNumber", "CompanyRegNumber" or "TrustNumber". Use /foreign-bank-account-verification for foreign passports. |
| bankAccountNumber | string | Required | Bank account number (7-13 digits) |
| bankBranchCode | string | Required | 6-digit branch code (e.g. "250655") |
| bankName | string | Optional | Optional bank name to improve account matching when available |
| bankAccountType | string | Required | "Unknown", "Savings", "Current", "Transmission", "Bond", or "SubscriptionShare" |
| mode | string | Required | "sandbox" or "production" |
curl -X POST https://www.verifynow.co.za/api/external/bank-account-verification \
-H "x-api-key: vn_live_abc..." \
-H "Idempotency-Key: unique-id" \
-d '{
"firstName": "John",
"surname": "Doe",
"identityNumber": "9604075249086",
"identityType": "IDNumber",
"bankName": "FNB",
"bankAccountNumber": "123456789",
"bankBranchCode": "250655",
"bankAccountType": "Savings",
"mode": "production"
}'# Company Verification Example
Note: Production API responses provide more comprehensive data.
Get supported banks
Free, API-key authenticated, and limited to 60 requests per minute per IP address and account.
| Supported banks | bankName | bankCodeSend as bankBranchCode |
|---|---|---|
| Absa Bank | ABSA | 632005 |
| Access Bank | ACCESS BANK | 410506 |
| African Bank | AFRICAN BANK | 430000 |
| Bidvest Bank | BIDVEST BANK | 462005 |
| Capitec Bank | CAPITEC BANK | 470010 |
| Discovery Bank | DISCOVERY BANK | 679000 |
| First National Bank (FNB) | FNB | 250655 |
| Grindrod Bank | GRINDROD BANK | 584000 |
| GoTyme Bank | TYME BANK | 678910 |
| Investec Bank | INVESTEC BANK | 580105 |
| Nedbank | NEDBANK | 198765 |
| Sasfin Bank | SASFIN BANK | 683000 |
| Standard Bank | STANDARD BANK | 051001 |
| Bank Zero | BANK ZERO | 888000 |
| OM Bank | OM BANK | 352000 |
| Old Mutual (Legacy) | OLD MUTUAL | 462005 |
| Al Baraka Bank | ALBARAKA BANK | 800000 |
| eNL Mutual Bank | ENL MUTUAL BANK | 353000 |
| Finbond Mutual Bank | FINBOND MUTUAL BANK | 589000 |
| Standard Chartered | STANDARD CHARTERED | 730020 |
Account age: lengthOpen in standard bank results and the legacy accountNumberLengthValid field in business, NPO and foreign-passport checks indicate whether the account has been open for at least three months. Yes/true means at least three months; No/false means under three months; unavailable/null means the bank did not supply the result. Existing API field names are retained for compatibility.
CDV means Check Digit Verification. It checks whether the account number passes the validation rules for the selected bank and branch. A CDV failure leaves account ownership, account-open status and name or identifier matches unconfirmed.
For POST /api/external/bank-account-verification, the customer-facing CDV error is "CDV Error. Check account details." in API responses and API logs. Business-bank jobs use the confirmation message described in their endpoint guide. Check the response’s credits_used or the job’s creditsUsed field for the recorded charge.
For POST /api/external/bank-account-verification, a returned CDV rejection retains HTTP 200 with success: false, response_code: 6 and credits_used: 0. Handle this as a validation failure and inspect the response body before continuing. Asynchronous endpoints retain their job-status and webhook response formats.
Check the bank, branch code and account number against the account holder’s bank confirmation. Keep leading zeros and distinguish Capitec Bank from Capitec Business. Correct the details before submitting a new verification with a new Idempotency-Key. For an existing asynchronous job, check its status before submitting a replacement.
These dedicated routes are separate from standard real-time bank-account verification. Store the returned job ID and your Idempotency-Key while waiting for the signed webhook.
curl --request POST 'https://www.verifynow.co.za/api/external/npo-bank-account-verification' --header 'x-api-key: YOUR_API_KEY' --header 'Content-Type: application/json' --header 'Idempotency-Key: unique-npo-check-001' --data '{
"companyName": "Example Community Organisation",
"bankName": "ABSA",
"bankAccountNumber": "1234567889",
"bankBranchCode": "632005",
"bankAccountType": "current",
"consentConfirmed": true,
"purpose": "Verify the organisation bank account",
"webhookUrl": "https://your-domain.example/webhooks/verifynow",
"webhookSecret": "replace-with-your-own-secret-at-least-32-characters",
"mode": "sandbox"
}'Note: Production API responses provide more comprehensive data.
Use the full NPO name. Use the full NPO name recorded by the bank for the account-name check. Abbreviated account labels can return a name mismatch.
This is an asynchronous check. POST /api/external/npo-bank-account-verification returns HTTP 202 with a job ID. Read the saved result or receive a signed webhook when bank processing finishes. Processing can take several hours or the next banking window.
Send x-api-key, Content-Type: application/json and a fresh Idempotency-Key for a new check. Keep the same key and body when retrying an uncertain submission.
{
"companyName": "Example Community Organisation",
"bankName": "ABSA",
"bankAccountNumber": "1234567889",
"bankBranchCode": "632005",
"bankAccountType": "current",
"consentConfirmed": true,
"purpose": "Verify the organisation bank account",
"webhookUrl": "https://your-domain.example/webhooks/verifynow",
"webhookSecret": "replace-with-your-own-secret-at-least-32-characters",
"mode": "sandbox"
}idnumber is optional; companyRegistrationNumber is an alias. If both are supplied, their values must agree. Enter the registration/ID number held by the bank when available. Omitted fields are reported as Not provided.
The account number must contain 7–13 digits and the branch code six digits. The endpoint accepts the bank name and branch code supplied; supported coverage depends on the bank. Supply the full NPO name in companyName (up to 160 characters) for a verified outcome. The API accepts a request with this field omitted; its completed result has a review outcome and reports the name check as Not provided. Account type is optional. Account types: current, cheque, savings, transmission, bond, credit-card or unknown.
consentConfirmed must be true. Purpose is 3–160 characters; webhookSecret is 32–256 characters. Supply a public HTTPS webhook URL. Mode is sandbox or production.
Verified means the account was found, is open and matches the full NPO name. A supplied account type or identifier must also match. An omitted ID remains Not provided and does not cause review. Missing or mismatched required checks return review.
checks.surnameMatch reports whether the supplied companyName matches the NPO account name held by the bank. This field keeps its existing API name. The response also retains initialsMatch; initials are optional and are excluded from the NPO outcome.
{
"id": "evt_00000000000040008000000000000001",
"type": "npo_bank.verification.completed",
"createdAt": "2026-10-29T10:00:00.000Z",
"data": {
"jobId": "00000000-0000-4000-8000-000000000001",
"status": "completed",
"mode": "production",
"reportType": "npo-bank",
"creditsUsed": 7,
"inputStatus": {
"idnumber": "Not provided",
"companyName": "Provided",
"initials": "Not provided",
"bankAccountType": "Provided"
},
"result": {
"outcome": "verified",
"inputStatus": {
"idnumber": "Not provided",
"companyName": "Provided",
"initials": "Not provided",
"bankAccountType": "Provided"
},
"checks": {
"accountFound": true,
"accountOpen": true,
"surnameMatch": true,
"accountTypeMatch": true,
"companyRegistrationMatch": "Not provided",
"initialsMatch": "Not provided",
"accountNumberLengthValid": true,
"acceptsCredits": true,
"acceptsDebits": true
},
"bank": {
"name": "ABSA",
"accountNumberLast4": "7889"
}
}
}
}GET /api/external/npo-bank-account-verification/jobs/{jobId} returns the owned job and its result at zero credits. Results are withheld while billing is pending.
POST /api/external/npo-bank-account-verification/jobs/{jobId}/retry-webhook with {} redelivers the saved result. Supply both webhook fields to change the receiver. It does not create another bank enquiry.
Events are npo_bank.verification.completed and npo_bank.verification.failed. Verify the HMAC-SHA256 signature over the timestamp and raw body, reject stale timestamps and deduplicate event IDs. Follow the bank webhook guide for signing and recovery. A job without a final result times out after 48 hours.
Sandbox uses synthetic data and zero credits. Account numbers ending in 90 return review; 91 simulates a submission failure. Other valid sandbox account numbers return positive name/account checks. Missing IDs remain Not provided.
For a specific case, send x-verifynow-sandbox-scenario with mode: sandbox and a fresh Idempotency-Key. This explicit scenario takes precedence over account suffixes. The header is ignored in production.
| Scenario | Outcome | Expected behaviour |
|---|---|---|
| verified_without_id | verified | Use the full name and omit both identifier fields. ID remains Not provided. |
| name_mismatch | review | The supplied NPO name does not match. |
| account_not_found | review | Account found and open are false. |
| closed_account | review | The account is found but closed. |
| account_type_mismatch | review | Supply a known account type; its match is false. |
| identity_mismatch | review | Supply an identifier; its match is false. |
| name_unavailable | review | The bank name-match result is unavailable (null). |
| verification_timed_out | failed | A failed callback carries verification_timed_out. |
Use https://www.verifynow.co.za/api/bank-verification/callback-check as a sandbox receiver with your own signing secret. Your production integration should use its own HTTPS receiver. Poll saved jobs at zero credits.
Production uses the configured NPO service price shown on pricing. Completed results, including review, use credits. Failed verifications use zero customer credits. Keep sufficient credits available until processing finishes.
companyNameRequiredcompanyRegistrationNumberRequiredbankNameRequiredbankAccountNumberRequiredbankBranchCodeRequiredbankAccountTypeRequiredconsentConfirmedRequiredpurposeRequiredwebhookUrlRequiredwebhookSecretRequiredmodeRequired| Name | Type | Required | Description |
|---|---|---|---|
| companyName | string | Required | Registered company name |
| companyRegistrationNumber | string | Required | String containing the registration or identity number held by the bank. Existing CIPC and SA ID formats retain their handling; other strings preserve letters and separators. Matching depends on bank support and records. |
| bankName | string | Required | Capitec Business or Mercantile Bank |
| bankAccountNumber | string | Required | Bank account number |
| bankBranchCode | string | Required | 450105 |
| bankAccountType | string | Required | unknown, current, cheque, savings, transmission, bond, or credit-card |
| consentConfirmed | boolean | Required | Must be true |
| purpose | string | Required | Lawful business purpose for the check |
| webhookUrl | string | Required | Public HTTPS callback URL |
| webhookSecret | string | Required | Signing secret containing 32–256 characters |
| mode | string | Required | sandbox or production |
curl -X POST https://www.verifynow.co.za/api/external/business-bank-account-verification \
-H "x-api-key: vn_live_abc..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: unique-id" \
-d '{
"companyName": "Example Business (Pty) Ltd",
"companyRegistrationNumber": "2020/123456/07",
"bankName": "Capitec Business",
"bankAccountNumber": "1234567890",
"bankBranchCode": "450105",
"bankAccountType": "current",
"consentConfirmed": true,
"purpose": "Supplier bank account ownership check",
"webhookUrl": "https://api.example.com/webhooks/verifynow",
"webhookSecret": "replace-with-at-least-32-characters",
"mode": "production"
}'Note: Production API responses provide more comprehensive data.
HTTP 202 confirms that the job was accepted. Store its jobId and use the existing status endpoint or signed webhook for the final outcome. Eligible checks can finish through real-time processing; batch checks can take several hours or wait for the next bank processing window. A supplier failure after acceptance appears in the job result and business_bank.verification.failed callback. Completed callbacks include verified or review results. Failed results include verification_failed or verification_timed_out. reportType remains foreign-bank for compatibility.
The nine checks are accountFound, accountOpen, accountNumberLengthValid, accountTypeMatch, companyRegistrationMatch, initialsMatch, surnameMatch, acceptsDebits and acceptsCredits. Each is true, false or null. Null means unavailable or undetermined. accountNumberLengthValid is the legacy API name for whether the account has been open for at least three months; it measures account age. The field name is retained for compatibility. companyRegistrationMatch is the identifier match; surnameMatch is the company/account-holder name match. Failed results contain error details instead of checks.
The outcome values are verified, review and failed. Review is final and uses business_bank.verification.completed. Verified requires accountFound, accountOpen, accountTypeMatch, companyRegistrationMatch and surnameMatch to be true. A false or null value among those five produces review. An account-type mismatch requires review so the submitted type can be checked. An explicit No for acceptsCredits or acceptsDebits also requires review. Initials and the account-age field accountNumberLengthValid remain informational; an account being under three months old is not a mismatch in submitted details.
The bank result has arrived and charging is outstanding. The saved result and callback are withheld until charging succeeds. The worker is scheduled every minute. Insufficient-credit retries are scheduled 15 minutes apart; billing exceptions retry after five minutes. There is no fixed maximum billing hold. Keep the required credits available until completion. The 48-hour bank-result timeout does not cap billing holds.
companyRegistrationNumber accepts a JSON string without an identifier-format or field-specific length check. Existing CIPC formats and 13-digit SA IDs retain their normalisation and mapping. Other strings retain letters, slashes, hyphens, case and whitespace. Use the identifier recorded by the bank. String acceptance does not establish bank support or a bank match.
Yes. Submit the sole proprietor’s passport number as a string in companyRegistrationNumber, with letters and separators intact. Use the passport number and account-holder name recorded by the bank. A match depends on those bank records.
Submit the account-holder name recorded by the bank in companyName. The backend derives the supplier fields from this value and companyRegistrationNumber, including legal suffixes for supported company registrations and given-name/surname fields for supported personal IDs. The submitted details remain available in the dashboard. surnameMatch reports the company/account-holder name match; null means unavailable. initialsMatch can be null when no separate initials comparison is returned. A name mismatch produces a completed review result. Sandbox matches are synthetic.
bankAccountType accepts unknown, current, cheque, savings, transmission, bond and credit-card. Values are case-insensitive and surrounding whitespace is trimmed. Current and cheque map to the same account type.
Set consentConfirmed to true after obtaining the authorisation required for the check, and retain supporting evidence. The API records the confirmation and timestamp. Purpose describes your lawful business reason. Example: Verifying that the merchant owns the bank account Yoco pays their sales proceeds into, for scheduled and ad hoc payouts. This wording fits the field limit; the purpose field does not itself obtain consent.
Production requires an Idempotency-Key; sandbox can generate one when omitted. This business-bank route stores the key against the account and job with no time-based expiry in the lookup. Reuse it only for the original request. An identical normalised payload resolves to the existing job; a changed payload returns 409. This is an exception to the general 72-hour retry guidance. Status reads show the saved job state.
Sandbox repeats from the same IP, endpoint and identifier have a two-second cooldown: HTTP 429 with Retry-After: 2. Production accepts concurrent submissions with a separate Idempotency-Key for each new verification. The bank verification service queues accepted batch jobs for processing; concurrent submission does not guarantee concurrent completion. The production handler defines no endpoint-specific rate or concurrency cap. Infrastructure and bank capacity still apply; confirm expected peak volumes before rollout.
Fixed callback IPs are not configured. Delivery requires public HTTPS. HMAC-SHA256 signs the timestamp, a dot and the raw JSON body with your webhookSecret; the header is x-verifynow-signature with value v1=<hex digest>. The secret is never included in the callback. Verify the signature using a constant-time comparison, check x-verifynow-timestamp within five minutes of your clock, and deduplicate using the event id inside the verified body in durable storage. A strong random secret and these checks authenticate the payload, detect changes and prevent repeated processing. Return 2xx within 15 seconds. Delivery retries use delays of 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours.
A valid account number ending in 90 produces a completed review result with accountFound and accountOpen false. Ending in 91 returns HTTP 502 at submission, before creating a job or callback. Other valid account numbers use the passing fixture. Use the optional x-verifynow-sandbox-scenario header to select the additional fixtures in the Sandbox test scenarios section. Requests without the header retain the account-ending behaviour described here. Sandbox is synthetic and does not establish bank support for an identifier. Use https://www.verifynow.co.za/api/bank-verification/callback-check as a signed sandbox receiver; append ?simulate=unauthorized to exercise delivery failure.
Use the same x-api-key and set mode to sandbox or production. Sandbox uses synthetic results, zero credits and no bank enquiry.
The entire JSON request body is limited to 4.5 MB by the hosting platform; larger payloads receive HTTP 413. This does not establish bank identifier limits. See the field table below. String lengths use JavaScript UTF-16 code units. Names and purpose collapse repeated whitespace and are trimmed before length checks. URL and secret are trimmed. New identifier strings are preserved as supplied.
CDV means Check Digit Verification. It checks whether the account number passes the validation rules for the selected bank and branch. A CDV failure leaves account ownership, account-open status and name or identifier matches unconfirmed. For this business-bank endpoint, a CDV or bank-detail rejection, or a real-time response without usable verification fields, ends the check with "Confirm bank details before retrying. No credits charged." A missing result leaves its underlying cause unconfirmed. The service keeps the submitted bank and branch; the merchant must confirm the details before submitting a corrected request with a new Idempotency-Key. Read result.error.message through the existing job-status response or business_bank.verification.failed callback. An administrative recheck of a previously charged job can instead return "Confirm bank details before retrying. No additional credits charged." The original charge remains recorded in creditsUsed.
| Field | Accepted length / requirement |
|---|---|
| companyName | 2–160; control characters rejected |
| companyRegistrationNumber | Required JSON string; no field-specific format or length check |
| purpose | 3–160 |
| webhookUrl | Required public HTTPS URL; maximum 2,048 |
| webhookSecret | 32–256; use a cryptographically random secret |
Send mode: "sandbox" and the optional x-verifynow-sandbox-scenario header on POST /api/external/business-bank-account-verification. Requests that omit the header keep their existing sandbox behaviour. The header selects the scenario; the example account numbers alone keep their existing results.
For the first six scenarios, every other check is true and the event is business_bank.verification.completed. Debit and credit acceptance do not determine the overall outcome. The timeout scenario sends business_bank.verification.failed with error.code verification_timed_out and no checks. It uses the next webhook delivery cycle without waiting 48 hours. All scenarios cost zero credits.
Use a fresh Idempotency-Key when changing scenarios. Repeating the same request and key returns the existing job; changing the scenario with the same key returns HTTP 409. Existing validation and the two-second sandbox cooldown apply. Account numbers ending 91 retain the HTTP 502 submission error, including when the header is present. A supported scenario overrides the review fixture for ending 90. An empty or unsupported scenario header in sandbox returns HTTP 400.
To switch to production, set mode: "production", remove the scenario header and submit real account details with a fresh Idempotency-Key. Production ignores the scenario header, including unsupported values, and uses the existing live verification and billing flow.
| Header value | Example account | Result | Outcome |
|---|---|---|---|
| company_registration_mismatch | 123456792 | companyRegistrationMatch: false | review |
| name_mismatch | 123456793 | surnameMatch: false | review |
| closed_account | 123456794 | accountOpen: false; accountFound: true | review |
| debits_rejected | 123456795 | acceptsDebits: false | verified |
| credits_rejected | 123456796 | acceptsCredits: false | verified |
| name_unavailable | 123456797 | surnameMatch: null | review |
| verification_timed_out | 123456798 | error.code: verification_timed_out | failed |
curl -X POST https://www.verifynow.co.za/api/external/business-bank-account-verification \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: sandbox-company-mismatch-001" \
-H "x-verifynow-sandbox-scenario: company_registration_mismatch" \
-d '{
"companyName": "Example Business (Pty) Ltd",
"companyRegistrationNumber": "2020/123456/07",
"bankName": "Capitec Business",
"bankAccountNumber": "123456792",
"bankBranchCode": "450105",
"bankAccountType": "current",
"consentConfirmed": true,
"purpose": "Sandbox integration testing",
"webhookUrl": "https://YOUR_DOMAIN/webhooks/verifynow",
"webhookSecret": "REPLACE_WITH_A_RANDOM_SECRET_OF_AT_LEAST_32_CHARACTERS",
"mode": "sandbox"
}'The completed example is a sandbox fixture. The failed example illustrates a production failure; sandbox suffix 91 returns an HTTP error before job creation.
{
"id": "evt_11111111111141118111111111111111",
"type": "business_bank.verification.completed",
"createdAt": "2026-10-26T10:00:00.000Z",
"data": {
"jobId": "11111111-1111-4111-8111-111111111111",
"status": "completed",
"mode": "sandbox",
"reportType": "foreign-bank",
"creditsUsed": 0,
"result": {
"outcome": "verified",
"checks": {
"accountFound": true,
"accountOpen": true,
"accountNumberLengthValid": true,
"accountTypeMatch": true,
"companyRegistrationMatch": true,
"initialsMatch": true,
"surnameMatch": true,
"acceptsDebits": true,
"acceptsCredits": true
},
"bank": {
"name": "CAPITEC BUSINESS",
"accountNumberLast4": "6789"
}
}
}
}{
"id": "evt_22222222222242228222222222222222",
"type": "business_bank.verification.failed",
"createdAt": "2026-10-26T10:00:00.000Z",
"data": {
"jobId": "22222222-2222-4222-8222-222222222222",
"status": "failed",
"mode": "production",
"reportType": "foreign-bank",
"creditsUsed": 0,
"result": {
"outcome": "failed",
"error": {
"code": "verification_failed",
"message": "The bank verification could not be completed"
},
"bank": {
"name": "CAPITEC BUSINESS",
"accountNumberLast4": "6789"
}
}
}
}GET /foreign-bank-account-verification/jobs/{jobId} and GET /business-bank-account-verification/jobs/{jobId} return the authenticated account’s saved status and result at zero credits. Billing-pending production results remain withheld.
POST to either job URL followed by /retry-webhook with an empty JSON object to retry delivery. Supply webhookUrl and webhookSecret together to correct the receiver. This uses the saved result and never restarts bank verification or billing. Existing submission payloads and HTTP 202 acknowledgements are unchanged.
Status, sandbox callback and recovery instructionsfirstNameRequiredsurnameRequiredpassportNumberRequiredpassportCountryRequiredbankNameRequiredbankAccountNumberRequiredbankBranchCodeRequiredbankAccountTypeRequiredconsentConfirmedRequiredpurposeRequiredwebhookUrlOptionalwebhookSecretOptionalmodeRequired| Name | Type | Required | Description |
|---|---|---|---|
| firstName | string | Required | Passport holder first name |
| surname | string | Required | Passport holder surname |
| passportNumber | string | Required | Foreign passport number |
| passportCountry | string | Required | Two-letter ISO country code |
| bankName | string | Required | Supported South African bank name |
| bankAccountNumber | string | Required | Bank account number |
| bankBranchCode | string | Required | Six-digit branch code |
| bankAccountType | string | Required | unknown, current, cheque, savings, transmission, bond, or credit-card |
| consentConfirmed | boolean | Required | Must be true |
| purpose | string | Required | Lawful business purpose for the check |
| webhookUrl | string | Optional | Public HTTPS callback URL |
| webhookSecret | string | Optional | Signing secret containing 32–256 characters |
| mode | string | Required | sandbox or production |
curl -X POST https://www.verifynow.co.za/api/external/foreign-bank-account-verification \
-H "x-api-key: vn_live_abc..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: unique-id" \
-d '{
"firstName": "Tariro",
"surname": "Moyo",
"passportNumber": "AB123456",
"passportCountry": "ZW",
"bankName": "FNB",
"bankAccountNumber": "1234567890",
"bankBranchCode": "250655",
"bankAccountType": "current",
"consentConfirmed": true,
"purpose": "Customer onboarding",
"webhookUrl": "https://api.example.com/webhooks/verifynow",
"webhookSecret": "replace-with-at-least-32-characters",
"mode": "production"
}'Idempotency-Key must be 8–160 characters in sandbox and production. The primary example is a completed real-time response. If real-time verification needs asynchronous fallback, supply webhookUrl and webhookSecret together; otherwise HTTP 503 returns ASYNC_FALLBACK_REQUIRES_WEBHOOK with creditsUsed: 0.
Note: Production API responses provide more comprehensive data.
Real-time consumer tracing and contact identification tools.
reportTypeRequiredidNumberRequiredmodeRequired| Name | Type | Required | Description |
|---|---|---|---|
| reportType | string | Required | "consumer_trace" |
| idNumber | string | Required | 13-digit SA ID number |
| mode | string | Required | "sandbox" (test) or "production" (live, uses credits) |
curl -X POST https://www.verifynow.co.za/api/external/verify \
-H "x-api-key: vn_live_abc123..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: unique-request-id" \
-d '{
"reportType": "consumer_trace",
"idNumber": "8803145123084",
"mode": "production"
}'Note: Production API responses provide more comprehensive data.
idNumberRequiredmodeRequired| Name | Type | Required | Description |
|---|---|---|---|
| idNumber | string | Required | 13-digit SA ID number |
| mode | string | Required | "sandbox" or "production" |
curl -X POST https://www.verifynow.co.za/api/external/address-lookup \
-H "x-api-key: vn_live_abc123..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: unique-request-id" \
-d '{
"idNumber": "8803145123084",
"mode": "production"
}'Note: Production API responses provide more comprehensive data.
idNumberRequiredmodeRequired| Name | Type | Required | Description |
|---|---|---|---|
| idNumber | string | Required | Valid 13-digit SA ID number |
| mode | string | Required | "sandbox" or "production" |
curl -X POST https://www.verifynow.co.za/api/external/property-search \
-H "x-api-key: vn_live_abc123..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: unique-request-id" \
-d '{
"idNumber": "8803145123084",
"mode": "production"
}'Note: Production API responses provide more comprehensive data.
idNumberRequiredmodeRequired| Name | Type | Required | Description |
|---|---|---|---|
| idNumber | string | Required | 13-digit SA ID number |
| mode | string | Required | "sandbox" or "production" |
curl -X POST https://www.verifynow.co.za/api/external/consumer-trace-lite \
-H "x-api-key: vn_live_abc123..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: unique-request-id" \
-d '{
"idNumber": "9103015257085",
"mode": "production"
}'Note: Production API responses provide more comprehensive data.
idNumberRequiredmodeRequired| Name | Type | Required | Description |
|---|---|---|---|
| idNumber | string | Required | 13-digit SA ID number |
| mode | string | Required | "sandbox" or "production" |
curl -X POST https://www.verifynow.co.za/api/external/consumer-trace-lite \
-H "x-api-key: vn_live_abc123..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: unique-request-id" \
-d '{
"idNumber": "9103015257085",
"mode": "production"
}'Note: Production API responses provide more comprehensive data.
reportTypeRequiredidNumberRequiredmodeRequired| Name | Type | Required | Description |
|---|---|---|---|
| reportType | string | Required | "marital-status-real-time" |
| idNumber | string | Required | 13-digit SA ID number |
| mode | string | Required | "sandbox" or "production" |
curl -X POST https://www.verifynow.co.za/api/external/verify \
-H "x-api-key: vn_live_abc123..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: unique-request-id" \
-d '{
"reportType": "marital-status-real-time",
"idNumber": "9103015257085",
"mode": "production"
}'Note: Production API responses provide more comprehensive data.
This alive/deceased check is not real-time: it reads cached records, which can lag behind Home Affairs. When you need the current Home Affairs status, use Enhanced Alive/Death Status instead.
idNumberRequiredmodeRequired| Name | Type | Required | Description |
|---|---|---|---|
| idNumber | string | Required | 13-digit SA ID number |
| mode | string | Required | "sandbox" or "production" |
curl -X POST https://www.verifynow.co.za/api/external/consumer-trace-lite \
-H "x-api-key: vn_live_abc123..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: unique-request-id" \
-d '{
"idNumber": "9103015257085",
"mode": "production"
}'Note: Production API responses provide more comprehensive data.
reportTypeRequiredcontactNumberRequiredmodeRequired| Name | Type | Required | Description |
|---|---|---|---|
| reportType | string | Required | "contact_enquiry" |
| contactNumber | string | Required | 10-digit SA phone number starting with 0 |
| mode | string | Required | "sandbox" (test) or "production" (live, uses credits) |
curl -X POST https://www.verifynow.co.za/api/external/verify \
-H "x-api-key: vn_live_abc123..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: unique-request-id" \
-d '{
"reportType": "contact_enquiry",
"contactNumber": "0821234567",
"mode": "production"
}'Note: Production API responses provide more comprehensive data.
reportTypeRequiredregistration_numberOptionalvat_numberOptionalsole_prop_id_numberOptionalmodeRequired| Name | Type | Required | Description |
|---|---|---|---|
| reportType | string | Required | "cipc_company_match" |
| registration_number | string | Optional | CIPC company registration number only, e.g. 2020/123456/07. Do not use this for bank account numbers, SA ID numbers, company names, customer references, or placeholders. |
| vat_number | string | Optional | SA VAT number (provide at least one identifier) |
| sole_prop_id_number | string | Optional | 13-digit SA ID number for sole proprietors only. Use this instead of registration_number for sole proprietor IDs. |
| mode | string | Required | "sandbox" or "production" |
curl -X POST https://www.verifynow.co.za/api/external/cipc \
-H "x-api-key: vn_live_abc123..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: unique-request-id" \
-d '{
"reportType": "cipc_company_match",
"registration_number": "2020/123456/07",
"mode": "production"
}'Identifier rules
registration_number must be a CIPC company registration number such as 2020/123456/07.vat_number for VAT numbers and sole_prop_id_number for sole proprietor SA ID numbers./bank-account-verification instead.registration_number first, then vat_number, then sole_prop_id_number.Note: Production API responses provide more comprehensive data.
reportTypeRequiredidNumberRequiredmodeRequired| Name | Type | Required | Description |
|---|---|---|---|
| reportType | string | Required | "cipc_director_search" |
| idNumber | string | Required | 13-digit SA ID number |
| mode | string | Required | "sandbox" or "production" |
curl -X POST https://www.verifynow.co.za/api/external/cipc \
-H "x-api-key: vn_live_abc123..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: unique-request-id" \
-d '{
"reportType": "cipc_director_search",
"idNumber": "8001015009087",
"mode": "production"
}'Note: Production API responses provide more comprehensive data.
Enterprise bundles provide access to advanced verification services through the /api/external/verify endpoint. Use either a bundle (combined reports) or reportType (single report).
Responsible verification infrastructure
VerifyNow connects dashboard and API workflows to authorised verification and data suppliers where a service requires it, then securely returns the result for onboarding, fraud prevention, FICA/customer due diligence (CDD), AML screening, supplier vetting, payment verification and compliance recordkeeping.
bundleRequiredidNumberRequiredmodeRequired| Name | Type | Required | Description |
|---|---|---|---|
| bundle | string | Required | "kyc_bundle" |
| idNumber | string | Required | 13-digit SA ID number |
| mode | string | Required | "sandbox" or "production" |
curl -X POST https://www.verifynow.co.za/api/external/verify \
-H "x-api-key: vn_live_abc123..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: unique-request-id" \
-d '{
"bundle": "kyc_bundle",
"idNumber": "8001015009087",
"mode": "production"
}'Note: Production API responses provide more comprehensive data.
bundleRequiredidNumberRequiredmodeRequired| Name | Type | Required | Description |
|---|---|---|---|
| bundle | string | Required | "employee_bundle" |
| idNumber | string | Required | 13-digit SA ID number |
| mode | string | Required | "sandbox" or "production" |
curl -X POST https://www.verifynow.co.za/api/external/verify \
-H "x-api-key: vn_live_abc123..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: unique-request-id" \
-d '{
"bundle": "employee_bundle",
"idNumber": "8001015009087",
"mode": "production"
}'Note: Production API responses provide more comprehensive data.
/verifynow?reportType=id-enhanced.idNumberRequiredmodeRequired| Name | Type | Required | Description |
|---|---|---|---|
| idNumber | string | Required | 13-digit SA ID number |
| mode | string | Required | "sandbox" or "production" |
curl -X POST https://www.verifynow.co.za/api/external/id-enhanced \
-H "x-api-key: vn_live_abc123..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: unique-request-id" \
-d '{
"idNumber": "8001015009087",
"mode": "production"
}'Note: Production API responses provide more comprehensive data.
Face match services compare a selfie photo against a reference image to verify identity. Available through the /api/external/facematch endpoint.
bundleRequiredmodeRequiredselfie_image_base64Requiredid_numberRequired| Name | Type | Required | Description |
|---|---|---|---|
| bundle | string | Required | "facematch" |
| mode | string | Required | "sandbox" or "production" |
| selfie_image_base64 | string | Required | Base64-encoded JPG/JPEG, PNG, WEBP, or TIFF selfie, with or without a data URL prefix; maximum 5 MB decoded |
| id_number | string | Required | 13-digit South African ID number |
curl -X POST https://www.verifynow.co.za/api/external/facematch \
-H "x-api-key: vn_live_abc123..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-d '{
"bundle": "facematch",
"mode": "production",
"selfie_image_base64": "data:image/jpeg;base64,/9j/4AAQ...",
"id_number": "8001015009087"
}'Note: Production API responses provide more comprehensive data.
bundleRequiredmodeRequiredselfie_image_base64Requiredreference_image_base64Required| Name | Type | Required | Description |
|---|---|---|---|
| bundle | string | Required | "facematch_standard" |
| mode | string | Required | "sandbox" or "production" |
| selfie_image_base64 | string | Required | Base64-encoded JPG/JPEG, PNG, WEBP, or TIFF selfie, with or without a data URL prefix; maximum 5 MB decoded |
| reference_image_base64 | string | Required | Base64-encoded JPG/JPEG, PNG, WEBP, or TIFF reference image; maximum 5 MB decoded |
curl -X POST https://www.verifynow.co.za/api/external/facematch \
-H "x-api-key: vn_live_abc123..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440001" \
-d '{
"bundle": "facematch_standard",
"mode": "production",
"selfie_image_base64": "data:image/jpeg;base64,/9j/4AAQ...",
"reference_image_base64": "data:image/jpeg;base64,/9j/4BBR..."
}'Note: Production API responses provide more comprehensive data.
bundleRequiredmodeRequiredselfie_image_base64Requiredreference_image_base64Requiredid_numberRequired| Name | Type | Required | Description |
|---|---|---|---|
| bundle | string | Required | "facematch_verified" |
| mode | string | Required | "sandbox" or "production" |
| selfie_image_base64 | string | Required | Base64-encoded JPG/JPEG, PNG, WEBP, or TIFF selfie, with or without a data URL prefix; maximum 5 MB decoded |
| reference_image_base64 | string | Required | Base64-encoded JPG/JPEG, PNG, WEBP, or TIFF reference image; maximum 5 MB decoded |
| id_number | string | Required | 13-digit South African ID number to verify |
curl -X POST https://www.verifynow.co.za/api/external/facematch \
-H "x-api-key: vn_live_abc123..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440002" \
-d '{
"bundle": "facematch_verified",
"mode": "production",
"selfie_image_base64": "data:image/jpeg;base64,/9j/4AAQ...",
"reference_image_base64": "data:image/jpeg;base64,/9j/4BBR...",
"id_number": "8001015009087"
}'Note: Production API responses provide more comprehensive data.
curl -X POST https://www.verifynow.co.za/api/external/passive-liveness \
-H "x-api-key: vn_live_abc123..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440003" \
-d '{
"mode": "production",
"image_base64": "/9j/4AAQSkZJRgABAQEASABIAAD..."
}'Note: Production API responses provide more comprehensive data.
modeRequireddocumentOptionaldocument_referenceOptionalexpected_first_nameOptionalexpected_last_nameOptionalexpected_addressOptionalexpected_countryOptionaldocument_passwordOptional| Name | Type | Required | Description |
|---|---|---|---|
| mode | string | Required | sandbox or production |
| document | file | Optional | Multipart PDF, JPG/JPEG, PNG, WebP or TIFF, up to 4 MB. Required unless document_reference is supplied. |
| document_reference | string | Optional | Reference returned by the private upload step for documents up to 15 MB. |
| expected_first_name | string | Optional | Expected first name for comparison. |
| expected_last_name | string | Optional | Expected last name for comparison. |
| expected_address | string | Optional | Expected address for comparison. |
| expected_country | string | Optional | Two- or three-letter country code. |
| document_password | string | Optional | Password for an encrypted PDF. |
curl -X POST https://www.verifynow.co.za/api/external/proof-of-address -H "x-api-key: YOUR_API_KEY" -H "Idempotency-Key: UNIQUE_REQUEST_KEY" -F "mode=sandbox" -F "document=@statement.pdf"The response below illustrates production. The sandbox request examples return testMode: true and creditCost: 0; remainingCredits can be absent.
Note: Production API responses provide more comprehensive data.
modeRequiredimage_base64Requiredminimum_ageOptionalrotate_imageOptional| Name | Type | Required | Description |
|---|---|---|---|
| mode | string | Required | "sandbox" or "production" |
| image_base64 | string | Required | Base64-encoded JPG/JPEG, PNG, WEBP, or TIFF face image, with or without a data URL prefix; maximum 5 MB decoded |
| minimum_age | number | Optional | Age threshold used for the status decision. Defaults to 18. |
| rotate_image | boolean | Optional | Set true if mobile captures may be sideways or upside down. |
curl -X POST https://www.verifynow.co.za/api/external/age-estimate \
-H "x-api-key: vn_live_abc123..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440004" \
-d '{
"mode": "production",
"image_base64": "/9j/4AAQSkZJRgABAQEASABIAAD...",
"minimum_age": 18
}'Note: Production API responses provide more comprehensive data.
Extract identity, address and bank-statement details from English PDFs or images. Results include consistency findings and optional name/address comparisons for review.
Identity document checks
Passport checks
Proof of Address powered by Document Intelligence
Bank statement checks
Checks depend on readable document content. The report identifies findings and checks that could not complete. OCR errors or document formatting can explain a finding; review the evidence before accepting the document.
Document Intelligence overviewStandard retail prices include VAT. Production checks use the configured credit price per document. Sandbox returns a fixed example at zero credits.
Use POST /api/external/document-intelligence or the iGaming upload step POST /api/external/igaming-onboarding/documents. Send your valid x-api-key, mode=production, authority_confirmed=true and a profile of auto, id, passport, poa or bank_statement.
Both Document Intelligence endpoints accept your existing valid API key without separate admin approval. Production requests require sufficient credits and authority to process the document.
For profile=id, both sides of a South African Smart ID are required in sandbox and production: multipart uses document for the front and back for the reverse; JSON uses document_base64 and back_base64. Missing either side returns 400 before analysis or charging. Identity details come from the back’s PDF417 barcode, checked against Code39; with identity_evidence=true, front OCR is also compared with the barcode identity fields. The front supplies the portrait. Supported files are PDF, JPEG, PNG, WebP and TIFF, up to 15 MB per file and ten pages per analysis. Optional fields are expected_name, expected_address , expected_id_number and password. Other profiles accept an optional back file.
Set enhanced_checks=true to opt into the dashboard’s additional bank, matching and coverage checks. Existing requests keep their default checks. Use this option with expected_id_number when you need an explicit incomplete result if the number cannot be extracted.
profile=passport accepts the passport photo page, including both MRZ lines. profile=auto with identity_evidence=true detects passports and identity documents from their content. Existing API requests retain their current analysis unless this option or the new Passport profile is selected. Passport fields include the name, passport number, nationality, birth date, issue date and expiry where readable. The MRZ reader accepts ICAO passport document subtypes such as PA. Check results.identity_analysis.printed_mrz_comparisons for agreement between printed fields and MRZ readings. ID front-to-barcode comparisons are in results.identity_analysis.front_barcode_comparisons. Each comparison provides field, printed_value, its mrz_value or barcode_value, status and requires_review. Outcomes include match, mismatch, partial_match, probable_match and quality_review. A text match can still require review when image quality limits confidence. For separate document analyses, read these fields on each item in results.documents.
results.identity_analysis.coverage_complete describes whether the required identity evidence was read; required_fields_missing identifies missing details. Check review_required and the comparison outcomes as well. MRZ check digits, barcode agreement and printed validity dates are document-consistency checks; issuer authenticity remains outside this service. The optional Basic SA ID verification uses its existing endpoint and configured price, currently one additional credit. It is called separately with a confirmed South African ID number.
Read results.fields, results.bank_statement.fields, results.findings and results.comparisons. Bank fields include the account holder, account number, bank and branch details where extracted. decision.status is review or checks_completed; the operator makes the acceptance decision.
Send Idempotency-Key on every check. Reuse the same key and input after a timeout; results replay for 72 hours without a second charge. A changed input with the same key returns 409. A pending request also returns 409. Two separate documents use two analyses: set secondary_profileto auto, passport, poa or bank_statement. Omit it or use back for the reverse of the first document. Results retain separate report sections. Supply secondary_passwordwhen the second PDF needs a different password. For an ID, omit secondary_profile or use back; submit each ID pair as its own request. A separate second ID is not supported.
For uploads above 4 MB in total, first POST JSON with action=upload,mode=production, filename, size andcontent_type. PUT the file to uploadUrl with the returnedheaders, then submit document_reference (andback_reference for a second file). Uploads expire after 15 minutes. Signed upload links are valid for 10 minutes; the 15-minute window applies to upload references. A completed check requiring review is charged. Processing failures incur no Document Intelligence charge. Refunds are handled by the support team.
Document Intelligence analysis runs in Johannesburg, South Africa, using VerifyNow’s proprietary engine. Application requests, temporary cloud uploads and encrypted retry results use Cape Town services.
Documents are used to perform the requested analysis. VerifyNow does not use these uploads to train models or send them to external AI services for analysis.
Uploads and connections to the analysis engine use HTTPS. Temporary cloud files use AES-256 server-side encryption. Stored analysis responses use AES-256-GCM encryption.
The engine uses temporary working files and removes them after processing. Large-upload links are valid for 10 minutes and upload references expire after 15 minutes. Temporary cloud files are deleted after processing or by expiry cleanup. Access expiry and physical deletion are separate; cleanup can finish after access expires.
Encrypted analysis responses use a 72-hour expiry in the active retry store, allowing the same request to be retried without another charge. Account, billing, consent and security records follow their own retention schedules. Infrastructure logs and backups follow the applicable provider schedules. These replay records are an exception to the default single-check report policy.
These locations describe the Document Intelligence processing workflow. Account databases, global edge services, support and payment providers have separate processing arrangements, including locations outside South Africa, as listed in the subprocessor register. Other verification services follow their own disclosures.
Requires engine 0.4.3 or later with enhanced_checks=true. Check results.engine_version and the presence of results.ai_origin before using this evidence. Sandbox responses are examples and do not analyse the uploaded file.
Enhanced checks inspect available Content Credentials and embedded metadata for declarations of AI generation or editing. Supported original image data inside PDFs is checked where it survives PDF creation.
results.ai_origin.method is offline_provenance_v1; network_fetching is false and pixel_classifier is not_run. Remote manifests are not fetched.
Read each entry in results.ai_origin.assets. scope identifies original_file or embedded_image; input identifies the upload, with page and image_index where available. Interpret status with ai_declared, ai_declaration_verified, cryptographic_integrity and signer_trusted. Properties may be absent when an asset could not be inspected.
| Status | Meaning |
|---|---|
trusted_ai_declaration | AI generation or editing is declared in provenance bound to the asset, with a signer trusted by the configured certificate list. |
signed_ai_declaration | The signed declaration is bound to the asset, but signer trust or certificate policy is not established. Review required. |
unsigned_ai_indicators | Unsigned metadata indicates AI generation or editing. The claim is unverified. |
provenance_invalid | Content-provenance validation failed. Review the source; this alone does not establish fraud. |
no_ai_declaration | Readable provenance contains no supported AI-generation declaration. Human origin is not established. |
not_established | No usable origin declaration was found. AI origin remains unknown. |
unavailable / unsupported / limit_reached / metadata_unavailable | The asset could not be fully checked, its format is unsupported, a processing bound was reached, or the PDF image stream lacks a supported original image container. |
AI_ORIGIN_DECLARED, AI_ORIGIN_UNVERIFIED and CONTENT_PROVENANCE_INVALID appear in results.findings when applicable. A flag calls for review; the signer’s trust applies to the origin declaration. It does not authenticate the bank or other document issuer.
Missing or removed metadata leaves AI origin unknown. This check does not classify the pixels for AI generation. A declaration can describe an embedded image without describing the whole statement. Issuer authenticity requires separate verification.
Phone verification for your application
Send a code to a South African mobile number, then check the code entered by the recipient. Use your existing API key and available credits. Your application owns account records and controls its verification journey.
Effective standard price: R0.75 per SMS. One allowance is reserved for each send or resend.
Standard retail prices include VAT. Your credit pack or assigned enterprise rate determines the effective cost. Sandbox uses 0 credits.
Every SMS uses the fixed template below. Only the server-generated code changes. Custom message text, brand prefixes, links and sender settings are unsupported. Requests containing extra fields return 400 UNSUPPORTED_FIELD.
Your verification code is 123456. It expires in 5 minutes. Do not share this code.
Use x-api-key on server-side calls. API customers can use their existing production key and available credits from their first OTP request. No separate OTP activation or daily spend cap applies. The credential selects the environment; omit mode. Always check environment before using a verified result in production.
A valid production API key works without admin approval or separate OTP activation. Account suspension, organization status, credit and sending limits still apply.
Sandbox sends no SMS, uses zero credits and accepts the fixed code 123456. The rate limits below also apply to sandbox. Admins can run send, verify and status checks from the admin OTP tester.
POST /api/external/otp/send accepts phoneNumber and an opaque reference of 1–128 characters. Optional endUserIp is a risk signal supplied by your server. Supply an Idempotency-Key of 1–200 characters. The example phone is a format placeholder.
curl -X POST https://www.verifynow.co.za/api/external/otp/send \
-H "x-api-key: $VERIFYNOW_API_KEY" \
-H "Idempotency-Key: signup-request-001" \
-H "Content-Type: application/json" \
-d '{"phoneNumber":"+27820000000","reference":"signup-opaque-001"}'{
"verificationId": "<opaque UUID>",
"environment": "production",
"dispatchStatus": "accepted",
"billingStatus": "charged",
"challengeStatus": "pending",
"expiresAt": "<ISO timestamp>",
"resendAt": "<ISO timestamp>",
"creditCost": "<pack credits when purchased; otherwise 0>",
"creditsCharged": "<pack credits charged by this request>",
"smsPackSize": 4,
"smsAllowanceStatus": "used",
"smsBalanceAfterRequest": 3,
"smsUnitsConsumed": 1,
"creditsReserved": 0
}Acceptance returns 200. An uncertain dispatch returns 202 with dispatchStatus unknown and billingStatus pending. After ten minutes unresolved, billingStatus becomes charged. Polling or repeating the send with its original key returns current state. Replays can change from 202 to 200 as acceptance is confirmed. They do not send a second SMS.
An in-progress same-key request returns 409 REQUEST_IN_PROGRESS with Retry-After. Changed input returns 409 IDEMPOTENCY_CONFLICT. Use a client HTTP timeout of at least 20 seconds. The delivery request has a ten-second timeout; retry uncertain requests with the original key.
curl -X POST https://www.verifynow.co.za/api/external/otp/verify \
-H "x-api-key: $VERIFYNOW_API_KEY" \
-H "Idempotency-Key: code-attempt-001" \
-H "Content-Type: application/json" \
-d '{"verificationId":"<verificationId>","code":"123456"}'POST /api/external/otp/verify returns verificationId, environment, status and verified. Status can be verified, invalid, expired, locked or superseded. Unknown or inaccessible challenges return 404 NOT_FOUND. Use a new idempotency key for each new code entry, and reuse it for retries of that entry.
Codes expire five minutes after creation and lock after five incorrect attempts. Success consumes the code. Retrying that successful request with its key returns the saved success. A distinct request against a consumed code returns expired.
A new dispatch supersedes the previous challenge for the same reference, including when its outcome is unknown. A later rejection does not restore the old code. The caller must retain verificationId; no phone registry is created.
GET /api/external/otp/verifications/{verificationId} returns current state with x-api-key. Poll at most 12 times per minute per challenge. Account polling and verification each default to 300 requests per minute; verification permits 30 requests per minute per challenge.
| Scope | Default limit | Behaviour |
|---|---|---|
| Send · per phone | 1 every 60 seconds | Applies across references and API keys for the account. |
| Send · per phone | 5 per hour; 10 per rolling 24 hours | Pending sends count towards the limits. |
| Send · per account | 100 per minute | Administrator-adjustable. |
| Verify · per challenge | 30 requests per minute | Five incorrect codes lock the challenge. |
| Verify · per account | 300 requests per minute | Administrator-adjustable. |
| Status · per challenge | 12 polls per minute | Polling sends no additional SMS. |
| Status · per account | 300 polls per minute | Administrator-adjustable. |
One credit buys four SMS sends at standard pricing. When the SMS balance is empty, the next send buys a four-send pack using prepaid credits. Unused sends remain available to the same account. Verification and status polling are included. A confirmed rejection before acceptance releases the reserved SMS allowance. Credit refunds are handled manually. Accepted sends remain used if handset delivery fails. An uncertain send reserves one allowance and uses it after ten minutes unless rejection is confirmed.
Pending sends count towards rate limits. Account limits may be adjusted by an administrator. A 429 response provides Retry-After. Shared IP traffic is a signal by default; account-specific IP blocking is optional.
| HTTP | Code | Action |
|---|---|---|
| 400 | UNSUPPORTED_FIELD | Remove custom text, brand, sender or other unsupported fields. SMS wording is fixed. |
| 400 | INVALID_PHONE_NUMBER / INVALID_CODE / INVALID_REFERENCE | Correct the request before retrying. |
| 400 | CREDENTIAL_ENVIRONMENT_REQUIRED | Use the appropriate API credential. Omit mode. |
| 401 | UNAUTHORIZED | Check the API credential. |
| 403 | OTP_SUSPENDED | Contact support about the account suspension. |
| 404 | NOT_FOUND | The verification is unavailable to this credential. |
| 409 | REQUEST_IN_PROGRESS | Retry the same request and key after Retry-After. |
| 409 | IDEMPOTENCY_CONFLICT | Use the original input or a new key for a new operation. |
| 422 | UNSUPPORTED_NUMBER | Supply a South African mobile number. |
| 429 | RATE_LIMITED | Wait for Retry-After. |
| 402 | INSUFFICIENT_CREDITS | Top up credits. |
| 502 | SMS_SEND_REJECTED | The send was rejected. Its SMS allowance is available again; purchased packs remain funded. |
| 503 | OTP_UNAVAILABLE | Retry an uncertain request with the same key. |
For processing, deletion and delivery-chain retention, read the OTP terms and retention disclosure. Keep codes and recipient numbers out of your application logs.
modeRequiredid_numberRequiredselfie_image_base64Requiredreference_image_base64Requiredminimum_ageOptionalrisk_levelOptionalexternal_customer_idOptionalfull_nameOptional| Name | Type | Required | Description |
|---|---|---|---|
| mode | string | Required | "sandbox" or "production" |
| id_number | string | Required | 13-digit South African ID number |
| selfie_image_base64 | string | Required | Base64-encoded JPG/JPEG, PNG, WEBP, or TIFF selfie; maximum 5 MB decoded |
| reference_image_base64 | string | Required | Base64-encoded JPG/JPEG, PNG, WEBP, or TIFF reference face image from your onboarding flow; maximum 5 MB decoded |
| minimum_age | number | Optional | Minimum acceptable age. Defaults to 18. |
| risk_level | string | Optional | "standard" or "high". High-risk users include AML/PEP. |
| external_customer_id | string | Optional | Your customer or player reference for duplicate signalling. |
| full_name | string | Optional | Recommended for high-risk AML/PEP screening. |
curl -X POST https://www.verifynow.co.za/api/external/igaming-onboarding \
-H "x-api-key: vn_live_abc123..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: player-onboarding-001" \
-d '{
"mode": "production",
"id_number": "8001015009087",
"selfie_image_base64": "/9j/4AAQSkZJRgABAQEASABIAAD...",
"reference_image_base64": "/9j/4AAQSkZJRgABAQEASABIAAD...",
"minimum_age": 18,
"risk_level": "high",
"external_customer_id": "player_12345",
"full_name": "Jane Doe",
"country": "za"
}'Note: Production API responses provide more comprehensive data.
VerifyNow does not publish one universal per-key rate tier for these endpoints. Treat operational limits as endpoint-specific unless your account agreement states otherwise.
| Limit Type | Limit | Notes |
|---|---|---|
| Published per-key tier | Not published | Route or account specific |
| Sandbox cooldown | 2 seconds | Same IP + endpoint + payload; playground and Postman share this lock. Production is not affected. |
| Image size | Endpoint-specific | No universal limit is promised here |
| Concurrency | Not published | Contact support for account requirements |
Do not rely on universal X-RateLimit-* headers. A route that applies a temporary cooldown can return Retry-After with its 429 response.
Contact our sales team to discuss route-specific throughput requirements for your integration: sales@verifynow.co.za .
Extract data from ID documents using OCR. Supports South African ID cards, passports, and driver's licenses. Available through the /api/external/id-document-verify endpoint.
bundleRequiredmodeRequiredfront_imageRequiredback_imageOptionalfront_image_base64Optionalback_image_base64Optionaldocument_typeOptionalissuing_countryOptional| Name | Type | Required | Description |
|---|---|---|---|
| bundle | string | Required | "id_document_verification" |
| mode | string | Required | "sandbox" or "production" |
| front_image | file | Required | TIFF, JPG/JPEG, PNG, WEBP, or PDF front image for multipart/form-data requests; maximum 5 MB |
| back_image | file | Optional | Optional TIFF, JPG/JPEG, PNG, WEBP, or PDF back image for multipart/form-data requests; maximum 5 MB |
| front_image_base64 | string | Optional | Base64-encoded JPG/JPEG, PNG, WEBP, or TIFF front image for JSON requests; maximum 5 MB decoded |
| back_image_base64 | string | Optional | Optional Base64-encoded JPG/JPEG, PNG, WEBP, or TIFF back image for JSON requests; maximum 5 MB decoded |
| document_type | string | Optional | Hint for document type (e.g., "Identity Card", "Passport") |
| issuing_country | string | Optional | 3-letter ISO country code (e.g., "ZAF") |
curl -X POST https://www.verifynow.co.za/api/external/id-document-verify \
-H "x-api-key: vn_live_abc123..." \
-H "Idempotency-Key: unique-request-id" \
-F "bundle=id_document_verification" \
-F "mode=production" \
-F "front_image=@front-id.jpg" \
-F "back_image=@back-id.jpg"Note: Production API responses provide more comprehensive data.
Authenticate a South African or supported foreign passport with POST /api/external/id-document-verify and bundle id_document_verification. Upload the full passport biodata page as front_image, or front_image_base64 for JSON. Include the page containing the MRZ. A second image is optional when the document requires another side or page. Production API requests use 2 credits per completed check. Basic SA ID verification is a separate 1-credit call when required.
Read results.id_verification for the document result. This example comes from a completed passport check on 10 October 2026. Personal details, dates and image data are replaced with placeholders to protect the passport holder. Additional fields, including image-quality scores and remainingCredits, can appear in the full response. Preserve nulls and missing fields when extraction supplies no value.
{
"success": true,
"requestId": "<your-idempotency-key>",
"results": {
"request_id": "<verification-reference>",
"id_verification": {
"status": "Approved",
"document_type": "Passport",
"document_subtype": "PASSPORT_GENERIC",
"document_number": "<redacted>",
"personal_number": "<redacted>",
"first_name": "<redacted>",
"last_name": "<redacted>",
"full_name": "<redacted>",
"issuing_state": "ZAF",
"issuing_state_name": "South Africa",
"nationality": "ZAF",
"date_of_birth": "<YYYY-MM-DD>",
"expiration_date": "<YYYY-MM-DD>",
"date_of_issue": "<YYYY-MM-DD>",
"portrait_image": "<base64 JPEG portrait omitted>",
"front_image": "<base64 JPEG document image omitted>",
"back_image": null,
"mrz": {
"surname": "<redacted>",
"name": "<redacted>",
"country": "ZAF",
"nationality": "ZAF",
"birth_date": "<YYMMDD>",
"expiry_date": "<YYMMDD>",
"sex": "<redacted>",
"document_type": "P",
"document_number": "<redacted>",
"optional_data": "<redacted>",
"birth_date_hash": "9",
"expiry_date_hash": "0",
"document_number_hash": "3",
"optional_data_hash": "4",
"final_hash": "4",
"personal_number": "<redacted>",
"warnings": [],
"errors": [],
"mrz_type": "TD3",
"mrz_string": "<two MRZ lines redacted>",
"mrz_key": "<redacted>"
},
"warnings": []
}
}
}| Field under results.id_verification | Meaning |
|---|---|
| document_number | Passport number extracted from the document. |
| nationality | Holder nationality as a three-letter country code. |
| issuing_state / issuing_state_name | Issuing-country code and name. issuing_country is an optional request hint; the observed production response uses issuing_state. |
| date_of_birth | Date of birth in YYYY-MM-DD format. |
| expiration_date / date_of_issue | Expiry and issue dates in YYYY-MM-DD format, when extracted. |
| first_name / last_name / full_name | Extracted holder names. |
| portrait_image | Cropped portrait as a base64 JPEG string when extracted. Check that it is populated before Face Match. |
| front_image / back_image | Returned document images. back_image was null for the single-page passport example. |
The mrz object contains the decoded machine-readable zone. A passport uses the TD3 layout in the observed example. Check-digit validation forms part of MRZ checking. All five check digits in the observed production passport passed a local recalculation against the returned MRZ. The response supplies the check-digit values and error/warning arrays; it has no separate mrz_valid boolean in this example.
| MRZ field | Meaning |
|---|---|
| mrz_type / mrz_string | Layout and raw MRZ text, with line breaks between the lines. |
| surname / name | Family and given names read from the MRZ. |
| country / nationality | Issuing-country and holder-nationality codes. |
| birth_date / expiry_date | MRZ dates in YYMMDD format. Use the top-level document dates for YYYY-MM-DD values. |
| document_type / document_number / sex | MRZ document type, passport number and sex marker. |
| optional_data / personal_number | Additional encoded information where present. These fields can contain identity numbers. |
| document_number_hash / birth_date_hash / expiry_date_hash | Printed check digits for the document number, date of birth and expiry date. |
| optional_data_hash / final_hash | Optional-data check digit where returned, and the composite check digit. |
| mrz_key | Composite MRZ key where returned. |
| errors / warnings | MRZ parsing and validation findings. Read these with the document-level warnings. |
Treat results.id_verification.status as an open string. The endpoint passes through the document decision; an exhaustive production enum has not been confirmed for this integration. The table explains client handling for the verdicts covered by the existing API guidance. Preserve additional values for review. HTTP 200 and success: true mean the request completed; your acceptance decision must use the document status, warnings and required fields.
| Returned status | Client handling |
|---|---|
| Approved | Assess the passed document decision against your required fields and returned warnings. This was the observed production passport result. |
| Declined | Treat the document as a failed check and inspect the warnings. |
| In Review | Send the result to your review process. A returned review verdict is a completed response. |
| Other, missing or null | Preserve the raw value and send the result for review before acceptance. |
Authenticity findings concern the submitted images. Document-level warnings contain a risk code, log_type severity and descriptions. The signal reference below describes documented document-check risks; the complete deployed warning-code set remains open. The observed passport returned warnings: [], mrz.errors: [] and mrz.warnings: []. The example includes image-quality scores. Separate numeric authenticity and tampering scores were absent. Treat absent forensic scores as unavailable evidence.
| Signal reference | Meaning |
|---|---|
| MRZ_VALIDATION_FAILED | MRZ checksum or format validation failed. |
| MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME | MRZ data and visible document text disagree. |
| SCREEN_CAPTURE_DETECTED | The document image appears to have been captured from a screen. |
| PRINTED_COPY_DETECTED | The image appears to show a printed copy. |
| PORTRAIT_MANIPULATION_DETECTED | The document portrait appears altered or replaced. |
| DOCUMENT_EXPIRED | The detected document expiry date has passed. |
This endpoint performs document-image checks. Issuing-authority record verification and NFC chip authentication require separate checks. A returned document decision should be considered together with your onboarding policy.
When the document meets your acceptance policy and portrait_image is populated, copy results.id_verification.portrait_image unchanged into reference_image_base64. Submit a current selfie as selfie_image_base64 to POST /api/external/facematch with bundle facematch_standard. This compares the two supplied images for South African and foreign passport holders. Each image has a maximum decoded size of 5 MB.
{
"bundle": "facematch_standard",
"mode": "production",
"reference_image_base64": "<portrait_image from the document response>",
"selfie_image_base64": "<base64 selfie>"
}Send x-api-key, Content-Type: application/json and a new Idempotency-Key for the Face Match operation. Reuse that key for retries with the same images. Read results.face_match.status and results.face_match.score. Face Match is a separate chargeable request. Assess selfie liveness through the separate Passive Liveness endpoint when your workflow requires it.
The initial passport request waits for processing and returns the completed result in that HTTP response. The processing call has a 55-second timeout. A concurrent retry with the same Idempotency-Key can return HTTP 202 with {"status":"pending"}. Repeat the same key and unchanged payload to retrieve a completed cached result. Processing failures and timeouts return HTTP 502. There is no passport job-polling URL or completion webhook in this endpoint.
Other request outcomes include 400 for invalid input, 401 for authentication failure, 402 for insufficient credits and 409 for an idempotency conflict or cached failure. Sandbox cooldown can return 429. The sandbox supplies mock data; use the production excerpt above to understand passport field placement.
Images travel over HTTPS from your server to VerifyNow and onward to the document-processing service. HTTPS protects transport; the processing service decodes the image to analyse the document. The VerifyNow API runtime is configured for Cape Town. The processing service publishes AWS Ireland (EU) as its default region. Account-specific processing placement and cache replica/backup locations require confirmation for any contractual residency commitment.
The endpoint handles uploaded files for processing and does not write the original uploads to a document archive. Saved verification sessions are disabled for the processing request. The returned portrait and document images are included in the API response, and VerifyNow caches that complete response for up to 72 hours to support idempotent retries. This temporary cache is image retention. Cache expiry describes the active replay record; backup and operational-log retention require separate confirmation.
The catalogue below lists passport-supported issuing countries and territories, including South Africa. Coverage was reviewed on 10 October 2026. Recognition depends on the document version and image quality. Use the passport issuing country when supplying the optional issuing_country hint; holder nationality is a separate response field. Catalogue entries include territories and special issuing authorities, so some codes are catalogue identifiers rather than ISO assignments.
Catalogue reviewed 2026-10-10
218 of 218 entries
| Code | Passport issuing country / territory |
|---|---|
| ABK | Abkhazia |
| AFG | Afghanistan |
| ALB | Albania |
| DZA | Algeria |
| AND | Andorra |
| AGO | Angola |
| AIA | Anguilla |
| ATG | Antigua and Barbuda |
| ARG | Argentina |
| ARM | Armenia |
| AUS | Australia |
| AUT | Austria |
| AZE | Azerbaijan |
| BHS | Bahamas |
| BHR | Bahrain |
| BGD | Bangladesh |
| BRB | Barbados |
| BLR | Belarus |
| BEL | Belgium |
| BLZ | Belize |
| BEN | Benin |
| BMU | Bermuda |
| BTN | Bhutan |
| BOL | Bolivia, Plurinational State of |
| BIH | Bosnia and Herzegovina |
| BWA | Botswana |
| BRA | Brazil |
| BRN | Brunei Darussalam |
| BGR | Bulgaria |
| BFA | Burkina Faso |
| BDI | Burundi |
| CPV | Cabo Verde |
| KHM | Cambodia |
| CMR | Cameroon |
| CAN | Canada |
| CYM | Cayman Islands |
| CAF | Central African Republic |
| TCD | Chad |
| CHL | Chile |
| CHN | China |
| COL | Colombia |
| COM | Comoros |
| COG | Congo |
| COD | Congo, The Democratic Republic of the |
| CRI | Costa Rica |
| HRV | Croatia |
| CUB | Cuba |
| CYP | Cyprus |
| CZE | Czechia |
| CIV | Côte d'Ivoire |
| DNK | Denmark |
| DJI | Djibouti |
| DMA | Dominica |
| DOM | Dominican Republic |
| DPR | Donetsk People's Republic |
| ECU | Ecuador |
| EGY | Egypt |
| SLV | El Salvador |
| GNQ | Equatorial Guinea |
| ERI | Eritrea |
| EST | Estonia |
| SWZ | Eswatini |
| ETH | Ethiopia |
| FRO | Faroe Islands |
| FJI | Fiji |
| FIN | Finland |
| FRA | France |
| GAB | Gabon |
| GMB | Gambia |
| GEO | Georgia |
| DEU | Germany |
| GHA | Ghana |
| GIB | Gibraltar |
| GRC | Greece |
| GRD | Grenada |
| GTM | Guatemala |
| GGY | Guernsey |
| GIN | Guinea |
| GNB | Guinea-Bissau |
| GUY | Guyana |
| HTI | Haiti |
| VAT | Holy See (Vatican City State) |
| HND | Honduras |
| HKG | Hong Kong |
| HUN | Hungary |
| ISL | Iceland |
| IND | India |
| IDN | Indonesia |
| IRN | Iran, Islamic Republic of |
| IRQ | Iraq |
| IRL | Ireland |
| IMN | Isle of Man |
| ISR | Israel |
| ITA | Italy |
| JAM | Jamaica |
| JPN | Japan |
| JEY | Jersey |
| JOR | Jordan |
| KAZ | Kazakhstan |
| KEN | Kenya |
| KIR | Kiribati |
| PRK | Korea, Democratic People's Republic of |
| KOR | Korea, Republic of |
| RKS | Kosovo |
| KWT | Kuwait |
| KGZ | Kyrgyzstan |
| LAO | Lao People's Democratic Republic |
| LVA | Latvia |
| LBN | Lebanon |
| LSO | Lesotho |
| LBR | Liberia |
| LBY | Libya |
| LIE | Liechtenstein |
| LTU | Lithuania |
| LPR | Lugansk People's Republic |
| LUX | Luxembourg |
| MAC | Macao |
| MDG | Madagascar |
| MWI | Malawi |
| MYS | Malaysia |
| MDV | Maldives |
| MLI | Mali |
| MLT | Malta |
| MHL | Marshall Islands |
| MRT | Mauritania |
| MUS | Mauritius |
| MEX | Mexico |
| FSM | Micronesia, Federated States of |
| MDA | Moldova, Republic of |
| MCO | Monaco |
| MNG | Mongolia |
| MNE | Montenegro |
| MSR | Montserrat |
| MAR | Morocco |
| MOZ | Mozambique |
| MMR | Myanmar |
| NAM | Namibia |
| NRU | Nauru |
| NPL | Nepal |
| NLD | Netherlands |
| NZL | New Zealand |
| NIC | Nicaragua |
| NER | Niger |
| NGA | Nigeria |
| MKD | North Macedonia |
| NOR | Norway |
| OMN | Oman |
| PAK | Pakistan |
| PLW | Palau |
| PSE | Palestine |
| PAN | Panama |
| PNG | Papua New Guinea |
| PRY | Paraguay |
| PER | Peru |
| PHL | Philippines |
| POL | Poland |
| PRT | Portugal |
| QAT | Qatar |
| ROU | Romania |
| RUS | Russian Federation |
| RWA | Rwanda |
| SHN | Saint Helena |
| KNA | Saint Kitts and Nevis |
| LCA | Saint Lucia |
| VCT | Saint Vincent and the Grenadines |
| WSM | Samoa |
| SMR | San Marino |
| STP | Sao Tome and Principe |
| SAU | Saudi Arabia |
| SEN | Senegal |
| SRB | Serbia |
| SYC | Seychelles |
| SLE | Sierra Leone |
| SGP | Singapore |
| SVK | Slovakia |
| SVN | Slovenia |
| SLB | Solomon Islands |
| SOM | Somalia |
| RSL | Somaliland |
| ZAF | South Africa |
| SSD | South Sudan |
| XOM | Sovereign Military Order of Malta |
| ESP | Spain |
| LKA | Sri Lanka |
| SDN | Sudan |
| SUR | Suriname |
| SWE | Sweden |
| CHE | Switzerland |
| SYR | Syrian Arab Republic |
| TWN | Taiwan |
| TJK | Tajikistan |
| TZA | Tanzania, United Republic of |
| THA | Thailand |
| TLS | Timor-Leste |
| TGO | Togo |
| TON | Tonga |
| TTO | Trinidad and Tobago |
| TUN | Tunisia |
| TKM | Turkmenistan |
| TCA | Turks and Caicos Islands |
| TUV | Tuvalu |
| TUR | Türkiye |
| UGA | Uganda |
| UKR | Ukraine |
| ARE | United Arab Emirates |
| GBR | United Kingdom |
| USA | United States |
| URY | Uruguay |
| UZB | Uzbekistan |
| VUT | Vanuatu |
| VEN | Venezuela, Bolivarian Republic of |
| VNM | Viet Nam |
| VGB | Virgin Islands, British |
| ESH | Western Sahara |
| YEM | Yemen |
| ZMB | Zambia |
| ZWE | Zimbabwe |
| ALA | Åland Islands |
Read South African driver's licence, Smart ID card, and vehicle licence disc barcodes. Smart ID identity fields come only from its back PDF417 barcode. Its front image supplies the printed portrait.
bundleRequiredimage_base64Optionalbarcode_base64Optionalauthority_confirmedRequiredbiometric_consent_confirmedOptionalselfie_image_base64OptionalmodeRequired| Name | Type | Required | Description |
|---|---|---|---|
| bundle | string | Required | "drivers_licence_barcode", "drivers_licence_identity", "drivers_licence_photo_match", or "drivers_licence_identity_cross_check" |
| image_base64 | string | Optional | JPG/JPEG, PNG or WebP image of the back of the licence; maximum 3 MB decoded. Use this or barcode_base64. |
| barcode_base64 | string | Optional | Complete 720-byte PDF417 payload encoded as base64. Use this or image_base64. |
| authority_confirmed | boolean | Required | Set true after confirming lawful authority and required privacy notices. |
| biometric_consent_confirmed | boolean | Optional | Required for the Home Affairs face-match and full verification bundles. |
| selfie_image_base64 | string | Optional | Required for drivers_licence_identity_cross_check. Current JPG/JPEG, PNG, WebP or TIFF face image; maximum 5 MB decoded. |
| mode | string | Required | "sandbox" or "production" |
curl -X POST https://www.verifynow.co.za/api/external/drivers-licence \
-H "x-api-key: vn_live_abc123..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: unique-request-id" \
-d '{
"bundle": "drivers_licence_barcode",
"image_base64": "BASE64_BACK_IMAGE",
"authority_confirmed": true,
"mode": "production"
}'Note: Production API responses provide more comprehensive data.
bundleRequiredfront_image_base64Requiredback_image_base64Requiredauthority_confirmedRequiredbiometric_consent_confirmedOptionalselfie_image_base64OptionalmodeRequired| Name | Type | Required | Description |
|---|---|---|---|
| bundle | string | Required | "smart_id_card_barcode", "smart_id_card_identity", "smart_id_card_photo_match", or "smart_id_card_identity_cross_check" |
| front_image_base64 | string | Required | Complete JPG/JPEG, PNG or WebP front image; maximum 5 MB decoded. Used only to crop the printed portrait. |
| back_image_base64 | string | Required | Complete JPG/JPEG, PNG or WebP back image; maximum 5 MB decoded. Its PDF417 barcode is the identity source. |
| authority_confirmed | boolean | Required | Set true after confirming lawful authority and required privacy notices. |
| biometric_consent_confirmed | boolean | Optional | Required for smart_id_card_photo_match and smart_id_card_identity_cross_check. |
| selfie_image_base64 | string | Optional | Required for smart_id_card_identity_cross_check. Current face image; maximum 5 MB decoded. |
| mode | string | Required | "sandbox" or "production" |
curl -X POST https://www.verifynow.co.za/api/external/smart-id-card \
-H "x-api-key: vn_live_abc123..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: unique-request-id" \
-d '{
"bundle": "smart_id_card_barcode",
"front_image_base64": "BASE64_FRONT_IMAGE",
"back_image_base64": "BASE64_BACK_IMAGE",
"authority_confirmed": true,
"mode": "production"
}'Note: Production API responses provide more comprehensive data.
/api/external/vehicle-licence-discbundleRequiredreport_typeRequiredimage_base64Optionalbarcode_textOptionalallow_visual_fallbackOptionalinclude_visual_fieldsOptionalauthority_confirmedRequiredmodeRequired| Name | Type | Required | Description |
|---|---|---|---|
| bundle | string | Required | "vehicle_licence_disc" |
| report_type | string | Required | "barcode", "plate", or "vin" |
| image_base64 | string | Optional | JPG/JPEG, PNG or WebP image of the disc; maximum 3 MB decoded. Use this or barcode_text. |
| barcode_text | string | Optional | Text returned by a PDF417 reader. Use this or image_base64. |
| allow_visual_fallback | boolean | Optional | Image requests only. Set true to read visible disc fields when glare or image quality prevents a PDF417 decode. The response returns processing: "visual_ocr" with medium or low confidence. The default is false. |
| include_visual_fields | boolean | Optional | Image requests only. Defaults to true. Set false to skip printed grossVehicleMassKg, tareKg, testDate, seatedPersons and standingPersons enrichment. fieldEvidence identifies the source and confidence for each returned field. barcode_text requests remain barcode-only. |
| authority_confirmed | boolean | Required | Set true after confirming lawful authority and required privacy notices. |
| mode | string | Required | "sandbox" or "production" |
curl -X POST https://www.verifynow.co.za/api/external/vehicle-licence-disc \
-H "x-api-key: vn_live_abc123..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: unique-request-id" \
-d '{
"bundle": "vehicle_licence_disc",
"report_type": "plate",
"image_base64": "BASE64_DISC_IMAGE",
"allow_visual_fallback": true,
"authority_confirmed": true,
"mode": "production"
}'Note: Production API responses provide more comprehensive data.
| HTTP | Code or state | Meaning |
|---|---|---|
| 202 | pending | An identical request is still running. |
| 400 | request validation | Invalid JSON, bundle, mode, report type, authority, flag value or input choice. |
| 402 | INSUFFICIENT_CREDITS | The account cannot cover the configured report credits. |
| 404 | VEHICLE_RECORD_NOT_FOUND | The selected plate or VIN comparison returned no matching record. No credits were used. |
| 409 | idempotency conflict | The key was reused with a changed payload or an invalid stored state. |
| 413 | request too large | The request body exceeds the scanner limit. |
| 422 | BARCODE_NOT_READABLE | The image did not yield a readable PDF417 barcode. |
| 422 | DISC_IMAGE_UNREADABLE | The requested visual-only fallback could not read the disc. |
| 422 | decoder outcome | The barcode was unsupported, incomplete or structurally invalid. |
| 429 | sandbox cooldown | Repeat the sandbox request after the Retry-After period. |
| 503 | comparison unavailable | The selected plate or VIN comparison service is unavailable. No credits were used. |
Look up a South African number plate with manufacturer specifications, and value a vehicle with the VerifyNow Valuation Engine. Each is charged separately and only when a result returns.
Build a consolidated vehicle report from a South African registration number. Choose one or more checks: microdot registration, insurance claims and damage history, or police interest. Vehicle details are included, with a free valuation when available. The VIN is obtained automatically.
Reports are processed asynchronously. Submit your request to receive a job ID, then use the GET endpoint below to check progress and retrieve the results. Each selected check has its own status, so you can see which results are available. Your credit total depends on the checks you select—use the calculator below to estimate the cost.
10 base + 0 selected checks
Select at least one check to request a report.
Registered make, model, year and VIN, plus engine number, colour and possible catalogue matches when available.
Estimated retail, market and trade values when available. Includes the mileage assumption, condition and confidence level used for the estimate.
Whether a microdot record exists, with its recorded make, model, derivative, colour, engine number and application date when available.
Recorded insurance claims, including accident dates, mileage, damage values and affected vehicle areas when available.
Whether police interest is recorded against the registration number. An unflagged result does not confirm that the registration exists.
Missing fields are returned as null. A no-record result does not guarantee that no history exists.
registrationNumberRequiredmodeRequiredchecksRequiredvinOptional| Name | Type | Required | Description |
|---|---|---|---|
| registrationNumber | string | Required | South African registration number. |
| mode | string | Required | sandbox or production |
| checks | array | Required | At least one: microdot, insuranceClaims, policeInterest. |
| vin | string | Optional | Optional VIN comparison, up to 64 letters and digits. vehicleDetails.data.vinMatched reports the match; blank skips comparison. The lookup uses the registration number. |
curl -X POST \
https://www.verifynow.co.za/api/external/comprehensive-vehicle-check \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: UNIQUE_REQUEST_KEY" \
-d '{
"mode": "sandbox",
"registrationNumber": "DEMO123GP",
"checks": [
"microdot",
"insuranceClaims",
"policeInterest"
]
}'Note: Production API responses provide more comprehensive data.
Retrieve your report using the job ID. Status is pending, completed or failed. Polling is free; partial reports identify unavailable checks.
Credits reserved for failed, unavailable or unrun checks are automatically refunded when processing finishes. If vehicle identification fails, all reserved credits are refunded. Completed checks, including valid “no records found” results, are charged. The billing breakdown shows quoted, currently reserved, charged and refunded credits. creditsUsed remains the final charge. Sandbox reserves and charges no credits.
jobIdRequired| Name | Type | Required | Description |
|---|---|---|---|
| jobId | string | Required | Job ID returned by submission, supplied in the URL path. |
curl \
https://www.verifynow.co.za/api/external/comprehensive-vehicle-check/jobs/JOB_ID \
-H "x-api-key: YOUR_API_KEY"Note: Production API responses provide more comprehensive data.
/api/external/number-plate-lookupOptional vin accepts up to 64 letters and digits. Comparison ignores letter case and leading/trailing whitespace. When vin is nonblank, vehicle.vinMatched is a boolean: true when it equals the returned VIN, false when different or no VIN is returned. Omitted, null or blank vin skips comparison and omits vinMatched. Invalid VIN input returns 400 before lookup or charging. Changing vin requires a new Idempotency-Key.
Submit a South African registration number. Get available registered identity, VIN, engine number, colour, year, region and vehicle code. Registered description and catalogue model are separate fields. All documented vehicle fields are present, with null for missing values and [] for no possibleModels. Each possibleModels entry includes model, vehicleCode, introYear and disconYear, with null for missing values. imageUrl, imageNote, billable and source are never returned.
possibleModels lists all returned catalogue alternatives. These are possible matches, not confirmed variants. Image URLs, images and image captions are omitted from this API. The dashboard may display a representative image through an authenticated VerifyNow endpoint; images are excluded from printed and PDF reports.
No valuation fields are returned. specifications is normally null; optional manufacturer specifications may be returned on a permitted fallback. Missing optional fields never invalidate a successful registration lookup.
Production charges once on a usable result. Reuse the UUID Idempotency-Key to replay a completed response. No result returns 404 VEHICLE_NOT_FOUND, invalid registration input returns 400 or 422 INVALID_REGISTRATION_NUMBER, and temporary failures return 503 LOOKUP_UNAVAILABLE. Error responses include success: false, error, code, creditsUsed: 0 and retryable. Retry-After is included when available.
Sandbox uses fictional VerifyNow test data with zero customer credits and no external calls. Allow up to 150 seconds for production fallback research.
Sandbox test plates: DEMO123GP succeeds; DEMO190GP returns 404 VEHICLE_NOT_FOUND; DEMO191GP returns 503 LOOKUP_UNAVAILABLE with retryable: true and Retry-After: 30; DEMO192GP succeeds without specifications; DEMO193GP returns 422 INVALID_REGISTRATION_NUMBER. No-result and invalid-input responses have retryable: false. The final two numeric digits select the scenario; these triggers only apply in sandbox.
registrationNumberRequiredvinOptionalmodeRequired| Name | Type | Required | Description |
|---|---|---|---|
| registrationNumber | string | Required | South African registration number, e.g. CA 123-456 or ABC123GP. |
| vin | string | Optional | Optional VIN to compare (up to 64 letters and digits). Returns vehicle.vinMatched when nonblank. |
| mode | string | Required | "sandbox" or "production" |
curl -X POST https://www.verifynow.co.za/api/external/number-plate-lookup \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6f1c2b8e-3d4a-4f5b-9c6d-7e8f9a0b1c2d" \
-d '{"registrationNumber":"DEMO123GP","vin":"AHTSANDBOX0000001","mode":"sandbox"}'The credit cost comes from the pricing table. If it is unavailable here, check /pricing before submitting a production request.
Note: Production API responses provide more comprehensive data.
Value a vehicle from its make, model and year with our proprietary VerifyNow Valuation Engine. Advertised asking prices from available South African vehicle listings are adjusted for year, mileage and condition. The response gives retail, market and trade values with ranges, demand, confidence and the comparables used (year, km and asking price).
Trade and market values use modelled dealer-margin assumptions. The demand field describes advertised listing availability; confidence describes uncertainty in the estimate. Original new prices are not supplied; newPrice remains null. Mileage is assumed from the vehicle age when omitted (mileageAssumed: true). To find the make, model and year from a number plate, call POST /number-plate-lookup first; it is charged separately.
Production charges once, only when a valuation returns. Too few comparable vehicles returns 422 NO_VALUATION with zero credits. Reusing an Idempotency-Key with the same body replays the saved result; a changed body returns 409; an in-progress request returns 202. Allow up to 200 seconds for a vehicle not valued recently. Limits: 8 KB JSON, 10 production requests per minute per account.
Sandbox returns fictional values for any vehicle, adjusted for mileage and condition, at zero credits. mileageKm 85090 returns 422 and 85091 returns 502.
makeRequiredmodelRequiredyearRequiredvariantOptionalmileageKmOptionalconditionOptionalmodeRequired| Name | Type | Required | Description |
|---|---|---|---|
| make | string | Required | Vehicle make, e.g. Toyota. |
| model | string | Required | Vehicle model, e.g. Hilux. |
| year | string | Required | Model year, YYYY, 1990 through the current year. |
| variant | string | Optional | Variant or derivative, e.g. 2.8 GD-6 Raider. Improves matching. |
| mileageKm | number | Optional | Whole kilometres. Assumed from age when omitted. |
| condition | string | Optional | excellent, good, fair or poor; defaults to good. |
| mode | string | Required | "sandbox" or "production" |
curl -X POST https://www.verifynow.co.za/api/external/vehicle-valuation/estimate \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 0b4e6a52-8f1d-4c3a-a9e2-5d7c1b3f9e40" \
-d '{"make":"Toyota","model":"Hilux","year":"2021","variant":"2.8 GD-6 Raider","mileageKm":85000,"condition":"good","mode":"sandbox"}'Note: Production API responses provide more comprehensive data.
Helper endpoints for checking API health and account status.
curl https://www.verifynow.co.za/api/external/healthNote: Production API responses provide more comprehensive data.
curl https://www.verifynow.co.za/api/external/my_credits \
-H "x-api-key: vn_live_abc123..."Note: Production API responses provide more comprehensive data.
The API uses standard HTTP response codes. Errors include a descriptive message.
| Code | Description |
|---|---|
200 | Success - request completed |
400 | Bad Request - invalid parameters |
401 | Unauthorized - invalid or missing API key |
402 | Payment Required - insufficient credits |
409 | Conflict - idempotency key reused with a different payload |
422 | NO_RECORD_FOUND — The Home Affairs lookup explicitly reported no identity record. Applies to POST /facematch with bundle: "facematch" only. No client charge: charged: false, credits_used: 0. |
422 | reference_photo_unavailable — No usable Home Affairs reference photo was returned. Applies to POST /facematch with bundle: "facematch" only. No client charge: charged: false, credits_used: 0. |
429 | Too Many Requests - rate limit exceeded |
502 | Verification failure - retry when the response includes Retry-After |
Production completed negatives versus could-not-complete errors. Sandbox no-record replies use charged: false and credits_used: 0. Sandbox reserved inputs are in Sandbox test triggers. In Review is a final HTTP 200 verdict, not a webhook.
| Endpoint | Negative | Error |
|---|---|---|
| SA ID /verify | HTTP 502 code NO_RECORD_FOUND, charged: true | HTTP 502 VERIFICATION_TEMPORARILY_UNAVAILABLE |
| Phone Lookup /verify (contact_enquiry) | HTTP 404 NO_RECORD_FOUND, charged: false, credits_used: 0 | HTTP 502 VERIFICATION_TEMPORARILY_UNAVAILABLE |
| ID + Photo with offline fallback /verify (home_affairs_id_photo_with_offline) | HTTP 502 NO_RECORD_FOUND, charged: false, credits_used: 0 | HTTP 502 VERIFICATION_TEMPORARILY_UNAVAILABLE |
| CIPC | HTTP 200 success false, No records found | HTTP 502 Processing failed |
| Facematch / liveness / ID document | HTTP 200 Declined or In Review | HTTP 502 Face match failed / liveness retry / ID document verification failed |
| Bank AVS | HTTP 200 success false, response_code 4 | HTTP 502 Processing failed |
Insufficient-credit response fields vary by endpoint. /verify and standard bank verification use requiredCredits and availableCredits; address lookup uses credits_required and credits_available. Some endpoints omit balances or code. Handle HTTP 402 and read the fields documented for the endpoint.