The Citizen Verification endpoint provides comprehensive access to citizen identity records within the national database. This endpoint enables authorized applications to retrieve detailed personal information for identity verification, compliance checks, and background verification processes.

Citizen Verification Overview

The citizen verification service allows you to query the national citizen registry using a South African identity number. The service returns comprehensive personal information including biographical data, document status, vital statistics, and reference numbers for cross-verification with other systems.

• 1. Token Generation: First, obtain an authentication token by calling the authentication endpoint with your credentials
• 2. Token Usage: Include the obtained token in the Authorization header for all subsequent API calls

Endpoint Details

• Endpoint: POST /api/CitizenData
• URL: {domain}/api/CitizenData
• Authentication Required: Yes (Bearer Token)

Headers Required:

{ 
"Content-Type": "application/json",
 "Authorization": "Bearer YOUR_TOKEN"
}

Request Parameters:

{
"identityNumber":""
}
                                        

Successful Response: Returns a JSON object containing your access token:

{
 "photo": "",
 "name": "",
 "surname": "",
 "smartCardIssued": "",
 "idIssueDate": "",
 "idSequenceNumber": "",
 "idNumberBlocked": "",
 "deceasedStatus": "",
 "dateOfDeath": "",
 "maritalStatus": "",
 "dateOfMarriage": "",
 "countryOfBirth": "",
 "identityNumber": "",
 "onHANIS": "",
 "onNPR": "",
 "hanisReference": "",
 "transactionNo": ""
}

• photo: Base64 encoded photograph from the citizen's identity document
• name: First name(s) of the citizen
• surname: Last name/family name of the citizen
• smartCardIssued: Boolean indicating if a smart ID card has been issued
• idIssueDate: Date when the identity document was issued
• idSequenceNumber: Sequence number of the identity document
• idNumberBlocked: Boolean indicating if the identity number is blocked/flagged
• deceasedStatus: Boolean indicating if the person is deceased
• dateOfDeath: Date of death (if applicable)
• maritalStatus: Current marital status
• dateOfMarriage: Date of marriage (if applicable)
• countryOfBirth: Country where the person was born
• identityNumber: The queried identity number
• onHANIS: Boolean indicating presence on Home Affairs National Identification System
• onNPR: Boolean indicating presence on National Population Register
• hanisReference: Reference number in the HANIS system
• transactionNo: Unique transaction number for this query

Error Response:

{  
  "message": "Error message here",
}   

Ensure to handle errors gracefully and prompt users to re-enter identity numbers if necessary.

const axios = require("axios");
const API_URL = "https://www.example.co.za/api/CitizenData";
const TOKEN = "Token_from_authentication";
const requestData = {
  identityNumber: "your_identity_number",
};
async function postData() {
  try {
    const response = await axios.post(API_URL, requestData, {
      headers: {
        Authorization: `Bearer ${TOKEN}`,
        "Content-Type": "application/json",
      },
    });
    console.log("DATA:", response.data); 
  } catch (error) {
    console.error("Error data:", error.response.data);
    console.error("Error status:", error.response.status);
    console.error("Error statusText:", error.response.statusText);
  }
}
postData();

$apiUrl = "https://www.example.co.za/api/CitizenData";
$token = "Token_from_authentication";

$context = stream_context_create([
    "http" => [
        "header" => "Authorization: Bearer $token\r\n" .
                    "Content-Type: application/json\r\n",
        "method" => "POST",
        "content" => json_encode([
                "identityNumber" => "your_identity_number"
            ]),
        "ignore_errors" => true
    ]
]);

$response = file_get_contents($apiUrl, false, $context);

if ($response === false) {
    echo "Error making request.";
} else {
    echo "Response: " . $response;
}