VerifyNow.co.za

POPIAFICAB-BBEE Level 1

Trusted by thousands of South African businesses

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