Buy Now
Lineage Verification

The Lineage Data endpoint provides comprehensive genealogical and family relationship information for South African citizens. This powerful service enables applications to retrieve detailed family trees, including parental information, children records, marriage history, and vital statistics for identity verification and genealogical research purposes.

Lineage Verification Overview

This API allows you to verify lineage data for South African citizens by providing their identity number. It returns detailed information about the individual's family relationships, including parents, children, and marital history.

  • 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/RefugeeData
  • URL: {domain}/api/RefugeeData
  • 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:


{
    "requestIdentifier": "",
    "idNumber": "",
    "newIdNumber": "",
    "idBlocked": "",
    "surname": "",
    "names": "",
    "maidenName": "",
    "dateOfBirth": "",
    "birthPlace": "",
    "deathStatus": "",
    "dateOfDeath": "",
    "deathPlace": "",
    "causeOfDeath": "",
    "marriageStatus": "",
    "marriageDate": "",
    "marriagePlace": "",
    "spouseId": "",
    "divorceDate": "",
    "addressLine1": "",
    "addressLine2": "",
    "postalCode": "",
    "children": [
        {
            "id": "",
            "gender": "",
            "status": ""
        },
        {
            "id": "",
            "gender": "",
            "status": ""
        }
    ],
    "mother": {
        "id": "",
        "surname": "",
        "names": ""
    },
    "father": {
        "id": "",
        "surname": "",
        "names": ""
    },
    "idBookDate": "",
    "idCardIndicator": "",
    "idCardDate": ""
}
  • requestIdentifier (string): Unique identifier for the request
  • idNumber (string): Original ID number from the request
  • newIdNumber (string): Updated ID number if applicable
  • idBlocked (string): Indicates if the ID is blocked or flagged
  • surname (string): Family name/surname
  • names (string): Given names
  • maidenName (string): Maiden name (if applicable)
  • dateOfBirth (string): Date of birth in YYYY-MM-DD format
  • birthPlace (string): Place of birth
  • deathStatus (string): Current death status
  • dateOfDeath (string): Date of death (if applicable)
  • deathPlace (string): Place of death (if applicable)
  • causeOfDeath (string): Cause of death (if applicable)
  • marriageStatus (string): Current marital status
  • marriageDate (string): Date of marriage
  • marriagePlace (string): Place of marriage
  • spouseId (string): Spouse's ID number
  • divorceDate (string): Date of divorce (if applicable)
  • addressLine1 (string): Primary address line
  • addressLine2 (string): Secondary address line
  • postalCode (string): Postal/ZIP code
  • mother (object): Mother's details
  • id (string): Mother's ID number
  • surname (string): Mother's surname
  • names (string): Mother's given names
  • father (object): Father's details
  • id (string): Father's ID number
  • surname (string): Father's surname
  • names (string): Father's given names
  • children (array): Array of up to 21 children records
  • id (string): Child's ID number
  • gender (string): Child's gender
  • status (string): Child's current status
  • idBookDate (string): Date of ID book issuance
  • idCardIndicator (string): ID card type indicator
  • idCardDate (string): Date of ID card issuance

Error Response:

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

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

Code Snippets

Use the following code snippets to interact with the Lineage Data API. These examples demonstrate how to make a POST request to retrieve lineage data using cURL, Node.js, and PHP.

Replace Token_from_authentication with your actual authentication token and your_identity_number with the identity number you want to verify.

Make sure to include the Authorization header with the Bearer token in all requests.

Choose your preferred programming language to see the code snippet:


const axios = require("axios");
const API_URL = "https://www.example.co.za/api/LineageData";
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/LineageData";
$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;
}