Documentation Index
Fetch the complete documentation index at: https://docs.didx.co.za/llms.txt
Use this file to discover all available pages before exploring further.
Overview
This endpoint requests identity information for a South African ID number from the Department of Home Affairs (DHA/NPR) and optionally runs a liveness check on a provided selfie.
To return a match, you must supply either:
- The ID number plus first name and last name, or
- The ID number plus a face image (base64)
This requirement is in line with SAFPS recommendations to ensure data is only shared with the correct individual.
Endpoint
POST /Citizen/RSAIDVerification
Request
curl -X POST "https://citizen.uat.securecitizen.cloud/Citizen/RSAIDVerification" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"ConsentReceived": true,
"IdNumber": "8001014800080",
"FirstNames": "John",
"LastName": "Doe",
"FaceString": "<base64_selfie>",
"RequestReason": "Customer onboarding",
"LivenessRequired": true,
"SAFPSRequired": true,
"IdentityCache": true,
"CachePreferred": false,
"CacheOnly": false,
"HANISImageRequired": true,
"CRef": "REF00001"
}'
Request Fields
| Field | Type | Required | Description |
|---|
ConsentReceived | boolean | Yes | Must be true, confirms subject consent was obtained |
IdNumber | string | Yes | South African 13-digit ID number |
RequestReason | string | Yes | Reason for the lookup (audited) |
FirstNames | string | Conditional | Required if FaceString is not provided |
LastName | string | Conditional | Required if FaceString is not provided |
FaceString | string | Conditional | Base64-encoded selfie image. Required if FirstNames/LastName not provided |
LivenessRequired | boolean | No | Set true to run a liveness check on the provided face image |
SAFPSRequired | boolean | No | Set true to include SAFPS fraud screening results |
IdentityCache | boolean | No | Allow cached DHA results if DHA is unavailable |
CachePreferred | boolean | No | Return cached result if available (only when IdentityCache: true) |
CacheOnly | boolean | No | Only return a cached result if one exists |
HANISImageRequired | boolean | No | Return the subject’s HANIS photo from DHA |
CRef | string | No | Your own transaction reference for tracking |
Subsidiary | string | No | Specify the entity the verification is performed for |
MobileNumber | string | No | Subject’s mobile number (0xxx format) |
Response
{
"title": "Citizen Api Output",
"status": 200,
"response": {
"TrackingNumber": "00000000-0000-0000-0000-000000000000",
"CachedResult": false,
"CacheDate": null,
"FirstNameResult": "70",
"LastNameResult": "70",
"IdNumber": "8001014800080",
"FirstName": "John",
"LastName": "Doe",
"SmartCardIssued": false,
"IDIssueDate": "20000101",
"IDSequenceNumber": "1",
"DeadIndicator": false,
"DateOfDeath": null,
"IDBlocked": false,
"MaritalStatus": null,
"DateOfMarriage": null,
"OnHanis": true,
"OnNPR": true,
"BirthPlaceCountryCode": "ZAF",
"BirthPlaceCountry": "South Africa",
"FacialImageAvailable": true,
"FacialImage": "<base64_image>",
"FaceResult": {
"isIdentical": true,
"confidence": 0.98
},
"LivenessResult": {
"LivenessResultScore": 1,
"LivenessResultProbability": 0.8,
"LivenessResultQuality": 0.8,
"LivenessResultClass": false,
"LivenessPassResult": true,
"LivenessMessage": "Liveness check successful"
},
"SAFPSResults": null,
"SCDerivedValues": null,
"IsWalletCreated": false,
"CRef": "REF00001",
"Status": "Success",
"Message": "Message"
}
}
Response Fields
| Field | Description |
|---|
CachedResult | true if the result was returned from cache rather than live DHA |
CacheDate | Date the cache record was last refreshed |
FirstNameResult | Similarity score (0–100) between provided first name and DHA record |
LastNameResult | Similarity score (0–100) between provided last name and DHA record |
IdNumber | ID number as found on DHA |
FirstName / LastName | Name as per DHA |
DeadIndicator | true if DHA records the individual as deceased |
IDBlocked | true if the ID has been flagged/blocked |
OnHanis | true if the individual is registered on HANIS |
OnNPR | true if the individual is registered on the NPR |
FacialImageAvailable | true if DHA has a photo on record |
FacialImage | Base64 HANIS photo (if HANISImageRequired: true) |
FaceResult.isIdentical | Whether the provided selfie matches the DHA photo |
FaceResult.confidence | Confidence score of the face match (0–1) |
LivenessResult.LivenessPassResult | true if the liveness check passed |
SAFPSResults | Array of SAFPS fraud listings (if SAFPSRequired: true) |
IsWalletCreated | true only when all validations pass and a wallet is created |
Message Codes
Common messages returned in the Message field:
| Message | Meaning |
|---|
Success | Successful lookup |
800 - IDNR is valid, but is not found on the NPR | ID number format is valid but not registered |
600 - IDNR marked for 'Deletion' on the NPR | ID is flagged for deletion on NPR |
10088 - NPR Not available, only photo is returned | NPR is offline; HANIS photo returned only |
Failure to get response - Error: Task cancelled, DHA is down | DHA is unavailable and no cache exists |
SAFPS Fetch Timed out. No cache record found. | SAFPS lookup timed out |
SAFPS Results
When SAFPS listings exist, the SAFPSResults array contains:
"SAFPSResults": [
{
"FirstName": "John",
"Surname": "Doe",
"BirthDate": "1980-01-01T00:00:00Z",
"Filings": [
{
"ReferenceNo": "SH00000001",
"Category": "Impersonation"
}
]
}
]
| Reference Format | Type | Description |
|---|
PR00000000 | Protective Registration | Subject has registered with SAFPS for protection |
VICTIM00000000 | Victim | Subject has been a victim of fraud |
SH00000000 | SAFPS Hit | Subject has been flagged for fraudulent activity |
