Skip to main content

​
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

FieldTypeRequiredDescription
ConsentReceivedbooleanYesMust be true — confirms subject consent was obtained
IdNumberstringYesSouth African 13-digit ID number
RequestReasonstringYesReason for the lookup (audited)
FirstNamesstringConditionalRequired if FaceString is not provided
LastNamestringConditionalRequired if FaceString is not provided
FaceStringstringConditionalBase64-encoded selfie image. Required if FirstNames/LastName not provided
LivenessRequiredbooleanNoSet true to run a liveness check on the provided face image
SAFPSRequiredbooleanNoSet true to include SAFPS fraud screening results
IdentityCachebooleanNoAllow cached DHA results if DHA is unavailable
CachePreferredbooleanNoReturn cached result if available (only when IdentityCache: true)
CacheOnlybooleanNoOnly return a cached result if one exists
HANISImageRequiredbooleanNoReturn the subject’s HANIS photo from DHA
CRefstringNoYour own transaction reference for tracking
SubsidiarystringNoSpecify the entity the verification is performed for
MobileNumberstringNoSubject’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

FieldDescription
CachedResulttrue if the result was returned from cache rather than live DHA
CacheDateDate the cache record was last refreshed
FirstNameResultSimilarity score (0–100) between provided first name and DHA record
LastNameResultSimilarity score (0–100) between provided last name and DHA record
IdNumberID number as found on DHA
FirstName / LastNameName as per DHA
DeadIndicatortrue if DHA records the individual as deceased
IDBlockedtrue if the ID has been flagged/blocked
OnHanistrue if the individual is registered on HANIS
OnNPRtrue if the individual is registered on the NPR
FacialImageAvailabletrue if DHA has a photo on record
FacialImageBase64 HANIS photo (if HANISImageRequired: true)
FaceResult.isIdenticalWhether the provided selfie matches the DHA photo
FaceResult.confidenceConfidence score of the face match (0–1)
LivenessResult.LivenessPassResulttrue if the liveness check passed
SAFPSResultsArray of SAFPS fraud listings (if SAFPSRequired: true)
IsWalletCreatedtrue only when all validations pass and a wallet is created

​
Message Codes

Common messages returned in the Message field:
MessageMeaning
SuccessSuccessful lookup
800 - IDNR is valid, but is not found on the NPRID number format is valid but not registered
600 - IDNR marked for 'Deletion' on the NPRID is flagged for deletion on NPR
10088 - NPR Not available, only photo is returnedNPR is offline; HANIS photo returned only
Failure to get response - Error: Task cancelled, DHA is downDHA 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 FormatTypeDescription
PR00000000Protective RegistrationSubject has registered with SAFPS for protection
VICTIM00000000VictimSubject has been a victim of fraud
SH00000000SAFPS HitSubject has been flagged for fraudulent activity