How do I authenticate requests to the VerifyNow API?

Every request must include an API key via the Authorization header as Bearer . API keys are scoped per account and can be rotated from the dashboard. Production requests should also include an Idempotency-Key header for safe retries.

What response format does the API use?

All endpoints return JSON. Successful responses use HTTP 200 with a consistent envelope containing a data object and a meta object (request id, credits spent, latency). Errors return a 4xx/5xx status with a structured error.code and error.message.

Are there rate limits?

Yes. Default rate limits are 60 requests per minute per API key, burstable to 120 per minute. Enterprise accounts can request higher limits. Exceeding the limit returns HTTP 429 with a Retry-After header.

How does webhook delivery work?

Long-running verifications (e.g. document authentication, liveness) can optionally deliver a webhook callback when they complete. Webhook endpoints must use HTTPS and cannot point to private, local, or cloud metadata addresses. Webhook payloads are signed with an HMAC-SHA256 signature in the X-VerifyNow-Signature header so you can verify authenticity.

Is there a sandbox environment?

Yes. Sandbox keys are available in the dashboard and hit the same endpoints with a sandbox. prefix. Sandbox requests do not consume credits and return deterministic fixture data for a documented set of SA ID numbers.

What data does the API store?

Request and response metadata (status, credits spent, latency, compliance audit trail) are stored for seven years as required by FICA Section 23. Personal payload data is stored per your account data-retention policy. All data is hosted in South Africa.

API Docs South Africa ID + Photo

External API

Africa ID Verification API

Use the same VerifyNow external API key model to run supported African identity checks, including Nigeria NIN via Smile ID. This is separate from the South African POST /verify report types.

Base URL

https://www.verifynow.co.za/api/external

Authentication

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 call the provider.

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.

POST /africa-verification

country

Supported country code

id_type

Supported ID type for the country

id_number

Identity number to verify

mode

sandbox or production

Optional matching fields: first_name, last_name, and dob in YYYY-MM-DD format.

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"
  }'

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": 10
}

Fetch Job Status

The status endpoint returns only jobs that belong to the API key owner. Provider 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}

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, PASSPORT, 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
Uganda	UG	NATIONAL_ID_NO_PHOTO	CM123456789012
Zambia	ZM	BANK_ACCOUNT, TPIN	1234567890123

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.

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)

VerifyNow API overview

The VerifyNow REST API lets South African businesses run identity verification, AML/PEP screening, CIPC checks, bank account verification, face match, and vehicle lookup from their own application. Authentication is via a Bearer API key; responses are JSON; pricing is per verification in credits.

Endpoints

Identity verification

POST /verify: Home Affairs SA ID verification with photo matching.
POST /verify-document: ID document authentication with OCR and fraud signals.
POST /face-match: Selfie-to-ID biometric match with confidence score.

Compliance screening

POST /aml-pep: AML/PEP/sanctions screening across 190+ countries.
POST /consumer-trace: Address, contact, and employment trace on an SA ID.
POST /consumer-trace-lite: Quick consumer contact and address lookup.

Business verification

POST /cipc/company: CIPC company registration and status check.
POST /cipc/director: Director search — all directorships for an SA ID.

Payments

POST /bank-account-verification: Real-time bank account ownership and validity.

Vehicle

POST /number-plate: Vehicle specs by registration number (57+ countries).
POST /vin-decode: Decode a 17-character VIN to vehicle specifications.

Developer FAQs

How do I authenticate requests to the VerifyNow API?: Every request must include an API key via the Authorization header as Bearer <YOUR_API_KEY>. API keys are scoped per account and can be rotated from the dashboard. Production requests should also include an Idempotency-Key header for safe retries.
What response format does the API use?: All endpoints return JSON. Successful responses use HTTP 200 with a consistent envelope containing a data object and a meta object (request id, credits spent, latency). Errors return a 4xx/5xx status with a structured error.code and error.message.
Are there rate limits?: Yes. Default rate limits are 60 requests per minute per API key, burstable to 120 per minute. Enterprise accounts can request higher limits. Exceeding the limit returns HTTP 429 with a Retry-After header.
How does webhook delivery work?: Long-running verifications (e.g. document authentication, liveness) can optionally deliver a webhook callback when they complete. Webhook endpoints must use HTTPS and cannot point to private, local, or cloud metadata addresses. Webhook payloads are signed with an HMAC-SHA256 signature in the X-VerifyNow-Signature header so you can verify authenticity.
Is there a sandbox environment?: Yes. Sandbox keys are available in the dashboard and hit the same endpoints with a sandbox. prefix. Sandbox requests do not consume credits and return deterministic fixture data for a documented set of SA ID numbers.
What data does the API store?: Request and response metadata (status, credits spent, latency, compliance audit trail) are stored for seven years as required by FICA Section 23. Personal payload data is stored per your account data-retention policy. All data is hosted in South Africa.