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 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.

VerifyNow

Home/API Docs/Integration Guide

Developer Guide

API Integration Guide

Step-by-step instructions for integrating the VerifyNow API into your application. From authentication to your first API call in minutes.

Get API Key

Go to Settings

API Reference

View full API documentation with all endpoints.

View API Docs

Test Sandbox

Test with sandbox mode - uses 0 credits.

"mode": "sandbox"

Get Your API Key

Create an account and obtain credentials

Sign up at verifynow.co.za
Navigate to Settings in your account
Find the API Key section
Copy your API key (starts with vn_live_ or vn_test_)

Security Warning

Keep your API key secret. Never expose it in client-side code or commit it to version control.

Set Up Your Environment

Configure environment variables

Store your API key as an environment variable:

# .env.local (or .env)
VERIFYNOW_API_KEY=vn_live_your_api_key_here

Make Your First API Call

Choose your preferred language

Using cURL

curl -X POST https://www.verifynow.co.za/api/external/verify \
  -H "x-api-key: $VERIFYNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "bundle": "id_verification",
    "idNumber": "8001015009087",
    "mode": "sandbox"
  }'

Using JavaScript/TypeScript

const response = await fetch(
  'https://www.verifynow.co.za/api/external/verify',
  {
    method: 'POST',
    headers: {
      'x-api-key': process.env.VERIFYNOW_API_KEY,
      'Content-Type': 'application/json',
      'Idempotency-Key': crypto.randomUUID(),
    },
    body: JSON.stringify({
      bundle: 'id_verification',
      idNumber: '8001015009087',
      mode: 'sandbox',
    }),
  }
);

const result = await response.json();

Using Python

import os
import uuid
import requests

response = requests.post(
    'https://www.verifynow.co.za/api/external/verify',
    headers={
        'x-api-key': os.environ['VERIFYNOW_API_KEY'],
        'Content-Type': 'application/json',
        'Idempotency-Key': str(uuid.uuid4()),
    },
    json={
        'bundle': 'id_verification',
        'idNumber': '8001015009087',
        'mode': 'sandbox',
    }
)

result = response.json()

Understand Idempotency

Prevent duplicate charges on retries

Required for Production

The Idempotency-Key header is required for all production API calls. It prevents duplicate charges.

How It Works

Generate a unique key (UUID) for each unique request
Send this key in the Idempotency-Key header
If you retry with the same key, you get the cached response (no duplicate charge)
Keys expire after 30 days

What Counts as Duplicate

Scenario	Result
Same Key + Same Body	Returns cached response (no charge)
Same Key + Different Body	409 Conflict error
Different Key + Same Body	New request (charges credits)

Test in Sandbox Mode

Risk-free testing before going live

Before going live, test everything with sandbox mode:

{
  "mode": "sandbox"
}

Sandbox Mode Benefits

Uses 0 credits
Returns realistic mock data
Works with any valid-format ID number

Handle Errors

Graceful error handling for production

Always handle API errors gracefully:

Code	Meaning	Action
`200`	Success	Process the response
`400`	Invalid parameters	Check your request body
`401`	Invalid API key	Check your API key
`402`	Insufficient credits	Top up your account
`409`	Idempotency conflict	Use a new Idempotency-Key
`429`	Rate limited	Slow down requests

Go Live

Deploy to production

When ready for production:

Switch to production mode:"mode": "production"
Ensure you have credits - Check balance via GET /my_credits
Always include Idempotency-Key for production requests
Monitor your usage in the VerifyNow dashboard

Security Checklist

API key stored as environment variable
API key never exposed in client-side code
Idempotency-Key used for all production requests
Error handling implemented
Tested in sandbox mode first

Consumer Trace: All-in-One Endpoint

The Consumer Trace endpoint (reportType: "consumer_trace") returns ALL of the following in a single call:

AddressData

Current and historical addresses (residential & postal)

EmploymentData

Employment history with employer names

ContactData

Phone numbers (cell and landline)

DefiniteMatchData

ID verification details

No need to make separate calls for address, employment, or phone data - it's all included.

Need Help?

For API support, contact us at support@verifynow.co.za

Full API Docs Get Started

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 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.