Documentation

API documentation

Complete guide to integrating South African ID validation into your application

Quick start

Get started with the Verify ID Number API in just a few minutes.

1

Get your API key

Sign up for a free account and generate your API key from the dashboard.

2

Make your first request

Use your API key to validate an ID number.

3

Integrate into your app

Follow our code samples below to integrate validation into your application.

Authentication

All API requests require authentication via an API key passed in the Authorization header.

Authorization header
Authorization: Bearer YOUR_API_KEY

Important security note

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

Endpoints

Validate single ID

GET

Validate a single South African ID number

Endpoint

GET https://api.verifyidnumber.co.za/v1/validate/:idNumber

Example request

curl https://api.verifyidnumber.co.za/v1/validate/8001015009083 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "idNumber": "8001015009083",
  "isValid": true,
  "dob": "1980-01-01",
  "age": 45,
  "gender": "M",
  "citizenship": "SA Citizen"
}

Validate multiple IDs

POST

Validate up to 100 ID numbers in a single request

Endpoint

POST https://api.verifyidnumber.co.za/v1/validate/bulk

Request body

{ 
  "idNumbers": [
    "8001015009083",
    "8202280009080",
    "9912311234567"
  ]
}

Example request

curl https://api.verifyidnumber.co.za/v1/validate/bulk \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"idNumbers":["8001015009083","8202280009080"]}'

Example response

[
  {
    "idNumber": "8001015009083",
    "isValid": true,
    "dob": "1980-01-01",
    "age": 45,
    "gender": "M",
    "citizenship": "SA Citizen"
  },
  {
    "idNumber": "8202280009080",
    "isValid": true,
    "dob": "1982-02-28",
    "age": 43,
    "gender": "F",
    "citizenship": "SA Citizen"
  }
]

Code examples

Integration examples in popular programming languages

JavaScript / Node.js

const API_KEY = 'YOUR_API_KEY';
const API_URL = 'https://api.verifyidnumber.co.za/v1/validate';

async function validateId(idNumber) {
  const response = await fetch(`${ API_URL}/{idNumber}`, {
    headers: {
      'Authorization': `Bearer ${ API_KEY}`
    }
  });
  
  const data = await response.json();
  return data;
}

// Usage
const result = await validateId('8001015009083');
console.log(result);

Python

import requests

API_KEY = 'YOUR_API_KEY'
API_URL = 'https://api.verifyidnumber.co.za/v1/validate'

def validate_id(id_number):
    headers = {'Authorization': f'Bearer {API_KEY}'}
    response = requests.get(f'{API_URL}/{id_number}', headers=headers)
    return response.json()

# Usage
result = validate_id('8001015009083')
print(result)

PHP

$apiKey = 'YOUR_API_KEY';
$apiUrl = 'https://api.verifyidnumber.co.za/v1/validate';

function validateId($idNumber) {
    global $apiKey, $apiUrl;
    
    $ch = curl_init("$apiUrl/$idNumber");
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Authorization: Bearer $apiKey"
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($response, true);
}

// Usage
$result = validateId('8001015009083');
print_r($result);

Rate limits

Rate limits vary by plan to ensure fair usage and optimal performance

Plan Requests/min Monthly quota
Free 10 100
Starter 100 5,000
Pro 300 Unlimited

Rate limit headers

All API responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.

Error handling

The API uses standard HTTP status codes to indicate success or failure

200

Success

Request completed successfully

400

Bad request

Invalid request parameters

401

Unauthorized

Invalid or missing API key

429

Too many requests

Rate limit or monthly quota exceeded

Need help?

Our team is here to help you integrate the API successfully