External API
Africa ID Verification API
Use the same VerifyNow external API key model to run supported African identity checks, including Nigeria NIN and Zimbabwe national ID checks. This is separate from the South African POST /verify report types.
Base URL
https://www.verifynow.co.za/api/externalAuthentication
Send your API key in the x-api-key header.
Sandbox
Set mode to sandbox for local mock results. Sandbox calls cost 0 credits and do not contact a live verification source.
Production Credits
6 credits per verification. This value follows the current pricing table.
Standard retail price includes VAT.
Start A Job
Production calls are asynchronous. The POST creates a verification job and returns a status URL. Use an Idempotency-Key header in production so retries cannot create duplicate jobs.
Keep the same Idempotency-Key and request body when retrying a production POST. While the original POST is still being processed, a replay can return HTTP 202 with status pending and requestId only, without jobId or statusUrl. Retry that POST with the same key and body, using a delay and client timeout. Once it returns jobId and statusUrl, use jobId for GET polling. requestId is not a job ID. Reusing the key with a different normalized request returns HTTP 409.
sandbox or productionAccepted country and id_type values. Zimbabwe uses NATIONAL_ID_NO_PHOTO.
first_name, last_name, and dob in YYYY-MM-DD format.Kenya KRA_PIN also accepts optional citizenship with the exact value Kenyan or Alien. Send identifiers as JSON strings to preserve leading zeros.
Nigeria NIN Example
curl -X POST https://www.verifynow.co.za/api/external/africa-verification \
-H "x-api-key: $VERIFYNOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"country": "NG",
"id_type": "NIN_V2",
"id_number": "12345678901",
"mode": "sandbox"
}'Zimbabwe National ID Example
curl -X POST https://www.verifynow.co.za/api/external/africa-verification \
-H "x-api-key: $VERIFYNOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"country": "ZW",
"id_type": "NATIONAL_ID_NO_PHOTO",
"id_number": "000000000A00",
"mode": "sandbox"
}'Zimbabwe IDs may be entered with spaces or hyphens. VerifyNow removes that display formatting before running the check.
POST Response
A successful production request returns pending. A successful sandbox request returns completed with a mock result available through the status endpoint.
{
"success": true,
"jobId": "3d4d83b0-0f76-4b58-9e6b-6b45cfac2db2",
"job_id": "3d4d83b0-0f76-4b58-9e6b-6b45cfac2db2",
"status": "pending",
"statusUrl": "https://www.verifynow.co.za/api/external/africa-verification/jobs/3d4d83b0-0f76-4b58-9e6b-6b45cfac2db2",
"mode": "production",
"reportType": "africa_verification_enhanced_kyc",
"requiredCredits": 6
}Fetch Job Status
The status endpoint returns only jobs that belong to the API key owner. Internal signatures and callback parameters are removed from returned results.
curl -X GET https://www.verifynow.co.za/api/external/africa-verification/jobs/{jobId} \
-H "x-api-key: $VERIFYNOW_API_KEY"GET /africa-verification/jobs/{jobId}Poll every 3 seconds while status is pending. Stop on completed or failed. This interval is integration guidance; completion time varies. Apply a client timeout and retain jobId so polling can resume.
success: true confirms that the job was retrieved. For completed jobs, result.ResultCode "1012" means a match and "1013" means no matching record. failed means the job encountered an error. result is null until a result is stored.
GET Response And Sandbox Flow
Sandbox supports job creation and GET retrieval with mock data at 0 credits. A successful POST returns HTTP 202 with status completed; fetch statusUrl to read the result. Sandbox completes during POST, so it does not simulate a pending transition or live-source timing. Use x-api-key on both requests; GET takes no request body or mode parameter.
Production jobs with ResultCode "1012" or "1013" are billable, including a completed no-match. The POST checks available credits; billing occurs when the job completes. GET status requests use 0 credits. Sandbox requests use 0 credits.
This example shows the Zimbabwe sandbox result. Job IDs and timestamps vary. Production result fields depend on the selected country and ID type. The response includes both jobId and job_id for the same job; updatedAt is an ISO timestamp or null.
{
"success": true,
"jobId": "3d4d83b0-0f76-4b58-9e6b-6b45cfac2db2",
"job_id": "3d4d83b0-0f76-4b58-9e6b-6b45cfac2db2",
"status": "completed",
"reportType": "africa_verification_enhanced_kyc",
"mode": "sandbox",
"result": {
"ResultCode": "1012",
"ResultText": "ID validated successfully",
"country": "ZW",
"id_type": "NATIONAL_ID_NO_PHOTO",
"id_number": "000000000A00",
"Actions": {
"Verify_ID_Number": "Verified",
"Return_Personal_Info": "Returned"
},
"FullName": "SANDBOX USER",
"DOB": "1990-01-01",
"meta": {
"environment": "sandbox",
"timestamp": "2026-10-10T08:00:00.000Z"
}
},
"updatedAt": "2026-10-10T08:00:00.000Z"
}To exercise a sandbox no-match, use Zimbabwe ID 000000000A90; the job completes with ResultCode 1013. ID 000000000A91returns HTTP 502 during POST and creates no job. Repeating the same sandbox request within the 2-second cooldown returns HTTP 429 with Retry-After: 2.
Supported Countries
| Country | Code | ID Types | Sandbox Example |
|---|---|---|---|
| Cote d'Ivoire | CI | NATIONAL_ID_NO_PHOTO, RESIDENT_ID_NO_PHOTO | 12345678901 |
| Ghana | GH | GHANA_CARD_NO_PHOTO, VOTER_ID | GHA-123456789-0 |
| Kenya | KE | ALIEN_CARD, KRA_PIN, NATIONAL_ID, TAX_INFORMATION, PASSPORT | 123456 |
| Nigeria | NG | BANK_ACCOUNT, BVN, NIN_V2, NIN_SLIP, V_NIN, PHONE_NUMBER, VOTER_ID | 0123456789 |
| Zambia | ZM | BANK_ACCOUNT, TPIN | 1234567890123 |
| Zimbabwe | ZW | NATIONAL_ID_NO_PHOTO | 000000000A00 |
Nigeria NIN
Use country: "NG" and id_type: "NIN_V2". The sandbox fixture shown in the docs is 12345678901. Matching name and date-of-birth fields are optional unless requested by your integration workflow.
South Africa ID + Photo
South African ID + Photo remains in the main API docs under Home Affairs ID Photo using reportType: "home_affairs_id_photo" on POST /verify.
Returned Data By Check
A successful record can return the fields listed below. Fields that are unavailable from the selected issuing source are omitted rather than estimated.
| Country | Check | Data returned | Important note |
|---|---|---|---|
| Cote d'Ivoire | National ID (No Photo)NATIONAL_ID_NO_PHOTO | Country, ID type and number, Full name, Date of birth, Gender, Address, Structured address | No photograph, phone number or document image is returned. |
| Cote d'Ivoire | Resident ID (No Photo)RESIDENT_ID_NO_PHOTO | Country, ID type and number, Full name, Date of birth, Gender, Address, Structured address | No photograph, phone number or document image is returned. |
| Ghana | Ghana Card (No Photo)GHANA_CARD_NO_PHOTO | Country, ID type and number, Full name, Date of birth, Gender | This Ghana Card check does not return a photograph. |
| Ghana | Voter IDVOTER_ID | Country, ID type and number, Issue date, Full name, Age, Photograph, Gender | The legacy voter ID returns age rather than a full date of birth. |
| Kenya | Alien CardALIEN_CARD | Country, ID type and number, Full name, Date of birth, Gender, Address, Structured address | No photograph, phone number or document image is returned. |
| Kenya | KRA PINKRA_PIN | Country, National ID number, KRA PIN as secondary ID number | This check returns the KRA PIN linked to the supplied Kenyan or alien ID, not a personal-information profile. |
| Kenya | National IDNATIONAL_ID | Country, ID type and number, Issue date, Full name, Date of birth, Photograph, Gender, Address, Structured address | Availability follows the issuing source record. |
| Kenya | Tax InfoTAX_INFORMATION | Country, ID type and number, Full name, Address, Structured address | No date of birth, photograph, phone number, document image or gender is returned. |
| Kenya | PassportPASSPORT | Country, ID type and number, Issue date, Expiry date, Full name, Date of birth, Photograph, Gender, Address, Structured address | Availability follows the issuing source record. |
| Nigeria | Bank AccountBANK_ACCOUNT | Country, ID type and account number, Account holder full name | The Nigeria bank-account check returns the account holder name only. |
| Nigeria | BVNBVN | Country, ID type and number, Issue date, Full name, Date of birth, Photograph, Phone number, Second phone number when available, Gender, Address, Structured address | Availability follows the issuing source record. |
| Nigeria | NIN V2NIN_V2 | Country, ID type and number, Full name, Date of birth, Photograph, Phone number, Gender, Address, Structured address | Availability follows the issuing source record. |
| Nigeria | NIN SlipNIN_SLIP | Country, ID type and number, Full name, Date of birth, Photograph, Phone number, NIN slip document image, Gender, Address, Structured address | Availability follows the issuing source record. |
| Nigeria | Virtual NINV_NIN | Country, ID type and number, Full name, Date of birth, Photograph, Phone number, Second phone number when available, Gender, Address, Structured address | Availability follows the issuing source record. |
| Nigeria | Phone NumberPHONE_NUMBER | First-name match result, Middle-name match result, Last-name match result, Date-of-birth match result, Gender match result | This phone-number check returns textual match results rather than a personal-information profile. |
| Nigeria | Voter IDVOTER_ID | Country, ID type and number, Full name, Year of birth, Photograph, Phone number, Gender, Address, Structured address | The date-of-birth field contains the year only for this check. |
| Zambia | Bank AccountBANK_ACCOUNT | Country, ID type and account number, Account holder full name, Phone number | Availability follows the issuing source record. |
| Zambia | TPINTPIN | Country, ID type and number, Full name | No date of birth, photograph, phone number, document image, gender or address is returned. |
| Zimbabwe | National ID (No Photo)NATIONAL_ID_NO_PHOTO | Country, ID type and number, First name, Last name, Full name, Date of birth, Gender, Alive status | No photograph, address, phone number or document image is returned. |
Bank Account Codes
For BANK_ACCOUNT checks, include a supported bank_code for the selected country.
NG
044 (Access Bank), 063 (Access Bank (Diamond Bank)), 050 (Ecobank), 084 (Enterprise Bank), 070 (Fidelity Bank), 011 (First Bank), 214 (FCMB), 058 (GTBank), 301 (Jaiz Bank), 082 (Keystone Bank), 014 (Mainstreet Bank), 076 (Polaris Bank), 221 (Stanbic IBTC), 232 (Sterling Bank), 032 (Union Bank), 033 (UBA), 215 (Unity Bank), 035 (Wema Bank)
ZM
543 (543), absa (Absa Bank), accessbank (Access Bank), airtel (Airtel), atma (Atlas Mara), boc (Bank of China), citibank (Citibank), ecobank (Ecobank), etumba (eTumba), indo (Indo Zambia), investrust (Investrust Bank), fab (First Alliance), firstcapital (First Capital), fnb (FBN), mtn (MTN), stanbic (Stanbic Bank), stanchart (Standard Chartered), tenga (Tenga), uba (UBA), zanaco (Zanaco), zamtel (Zamtel), zicb (ZICB), zoona (Zoona)