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.
Get your API key
Sign up for a free account and generate your API key from the dashboard.
Make your first request
Use your API key to validate an ID number.
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: 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
GETValidate 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
POSTValidate 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
Success
Request completed successfully
Bad request
Invalid request parameters
Unauthorized
Invalid or missing API key
Too many requests
Rate limit or monthly quota exceeded