API Reference

SA ID Validation API

Integrate South African ID validation into your app with one simple JSON request. Send an idNumber and receive validation status, checks, and derived identity details in the response.

Base URL

https://api.idvalid.co.za

Endpoint

POST /api/v1/validate

Content Type

application/json

Getting Started

1. Send a POST request

Call /api/v1/validate with a JSON body containing the ID number.

2. Read the JSON response

Check isValid, then use derivedData for values like date of birth, age, gender, and citizenship.

3. Handle failed checks

If isValid is false, inspect the errors and checks fields to understand what failed.

Quick Start

Here is the simplest way to integrate with the API.

cURL

curl -X POST "https://api.idvalid.co.za/api/v1/validate" \
  -H "Content-Type: application/json" \
  -d '{
    "idNumber": "9001015800085"
  }'

JavaScript

const response = await fetch("https://api.idvalid.co.za/api/v1/validate", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    idNumber: "9001015800085",
  }),
});
 
const data = await response.json();
 
if (!response.ok) {
  throw new Error("Validation request failed");
}
 
if (data.isValid) {
  console.log(data.derivedData);
} else {
  console.log(data.errors);
}

Request Body

Field	Type	Required	Description
idNumber	string	Yes	A South African ID number to validate.

Response

A successful request returns JSON like this:

JSON Response

{
  "normalizedValue": "9001015800085",
  "isValid": true,
  "checks": {
    "length": {
      "status": "Passed",
      "errorCode": null
    },
    "checksum": {
      "status": "Passed",
      "errorCode": null
    }
  },
  "errors": [],
  "derivedData": {
    "dateOfBirth": "1990-01-01",
    "age": 36,
    "gender": "male",
    "citizenship": "South African citizen"
  }
}

Main fields

normalizedValueNormalized version of the ID number.
isValidWhether the ID number passed validation.
errorsList of validation errors, if any.
checksRule-by-rule validation results.

Derived data

dateOfBirthBirth date when available.
ageDerived age.
genderGender information.
citizenshipCitizenship status when available.

Using the Site Proxy

If you are integrating inside this Next.js app, you can use the built-in proxy route instead of calling the upstream API directly.

Proxy route

POST /api/validate-id

This route accepts the same JSON body and forwards the request to the validation service on the server.

Frontend Example

const response = await fetch("/api/validate-id", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    idNumber: "9001015800085",
  }),
});
 
const data = await response.json();

Error Handling

Status	Meaning
200	Request processed. Check `isValid` in the response body.
400	Missing `idNumber` or invalid JSON body.
502	The validation service could not be reached when using the site proxy route.

Ready to test the integration?

Start with one validation request, confirm the response shape in your app, then wire the returned fields into your form or verification flow.

View Quick Guide View Pricing