Skip to main content

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 verifies a refugee’s identity using their NIIS file number against the Department of Home Affairs’ National Immigration Information System. Optionally includes liveness detection and biometric face matching. To return a match, you must supply either:
  • The file number plus first name and last name, or
  • The file number plus a face image (base64)

​
Endpoint

POST /Citizen/RefugeeVerification

​
Request

curl -X POST "https://citizen.uat.securecitizen.cloud/Citizen/RefugeeVerification" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "ConsentReceived": true,
    "FileNumber": "ABCDEF01345678",
    "FirstNames": "John",
    "LastName": "Doe",
    "RequestReason": "Customer onboarding",
    "LivenessRequired": true,
    "NIISImageRequired": true,
    "CRef": "REF00001"
  }'

​
Request Fields

FieldTypeRequiredDescription
ConsentReceivedbooleanYesMust be true
FileNumberstringYesRefugee NIIS file number
RequestReasonstringYesReason for the lookup (audited)
FirstNamesstringConditionalRequired if FaceString is not provided
LastNamestringConditionalRequired if FaceString is not provided
FaceStringstringConditionalBase64 selfie. Required if FirstNames/LastName not provided
LivenessRequiredbooleanNoRun a liveness check on the provided selfie
NIISImageRequiredbooleanNoReturn the subject’s photo from NIIS
CRefstringNoYour transaction reference
SubsidiarystringNoEntity the verification is performed for
MobileNumberstringNoSubject’s mobile number (0xxx format)

​
Response

{
  "title": "Citizen Api Output",
  "status": 200,
  "response": {
    "TrackingNumber": "string",
    "CachedResult": true,
    "firstNameResult": "70",
    "lastNameResult": "70",
    "niisFileNumber": "ABCDEF01345678",
    "firstName": "John",
    "lastName": "Doe",
    "gender": "M",
    "birthDate": "1990-01-01",
    "age": 35,
    "country": "Country of Origin",
    "nationality": "Nationality",
    "alternativeFileNumber": null,
    "officeOfApplication": "Johannesburg",
    "fileStatus": "Active",
    "permitNumber": "Permit Number",
    "expiryDate": "Monday, 12/02/2026; 24:00",
    "refugeeIDNumber": "Refugee ID Number",
    "facialImage": "<base64_image>",
    "FaceResult": {
      "isIdentical": true,
      "confidence": 0.97
    },
    "LivenessResult": {
      "LivenessPassResult": true,
      "LivenessMessage": "Liveness check successful"
    },
    "CRef": "REF00001",
    "Status": "Success",
    "Message": "string"
  }
}

​
Response Fields

FieldDescription
firstNameResult / lastNameResultSimilarity score (0–100) vs NIIS record
niisFileNumberConfirmed NIIS file number
fileStatusCurrent status of the refugee file
permitNumberAssociated permit number
expiryDatePermit expiry date
refugeeIDNumberRefugee ID number
facialImageBase64 NIIS photo (if NIISImageRequired: true)
FaceResult.isIdenticalWhether the provided selfie matches the NIIS photo
LivenessResult.LivenessPassResulttrue if liveness check passed