Skip to main content

​
Overview

These endpoints validate a physical South African ID document using OCR scanning, barcode reading, and authenticity checks. Three tiers are available depending on how much biometric verification you need.

Document Only

Validate the document and extract data via OCR

Document + Photo

Validate document and match face against a selfie

Document + Photo + Liveness

Full validation with liveness detection

​
Validate RSA ID Document

POST /Citizen/ValidateRSAIDDoc
Validates the document only — no face matching. 
curl -X POST "https://citizen.uat.securecitizen.cloud/Citizen/ValidateRSAIDDoc" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "ConsentReceived": true,
    "DocumentImage": "<base64_front_of_id>",
    "CRef": "REF00001"
  }'

​
Validate RSA ID Document + Photo

POST /Citizen/ValidateRSAIDDocAndPhoto
Validates the document and matches the face from the document against a provided selfie. 
curl -X POST "https://citizen.uat.securecitizen.cloud/Citizen/ValidateRSAIDDocAndPhoto" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "ConsentReceived": true,
    "DocumentImage": "<base64_front_of_id>",
    "FaceString": "<base64_selfie>",
    "CRef": "REF00001"
  }'

​
Validate RSA ID Document + Photo + Liveness

POST /Citizen/ValidateRSAIDDocAndPhotoWithLiveness
Full validation: document authenticity + face match + liveness detection. 
curl -X POST "https://citizen.uat.securecitizen.cloud/Citizen/ValidateRSAIDDocAndPhotoWithLiveness" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "ConsentReceived": true,
    "DocumentImage": "<base64_front_of_id>",
    "FaceString": "<base64_selfie>",
    "CRef": "REF00001"
  }'

​
Response

{
  "response_object": {
    "ocr_result": {
      "document_number": "8001014800080",
      "validation_passed": "valid",
      "comparison_field_list": [
        {
          "field_name": "DOCUMENT_NUMBER",
          "visual_zone_value": "8001014800080",
          "barcode_value": "8001014800080",
          "visual_barcode_match_ind_tristate": "true",
          "valid_ind_tristate": "true"
        },
        {
          "field_name": "DATE_OF_BIRTH",
          "visual_zone_value": "1980-01-01",
          "barcode_value": "1980-01-01",
          "visual_barcode_match_ind_tristate": "true",
          "valid_ind_tristate": "true"
        },
        {
          "field_name": "SURNAME",
          "visual_zone_value": "DOE",
          "valid_ind_tristate": "true"
        },
        {
          "field_name": "GIVEN_NAME",
          "visual_zone_value": "JOHN",
          "valid_ind_tristate": "true"
        },
        {
          "field_name": "SEX",
          "visual_zone_value": "M",
          "barcode_value": "M",
          "visual_barcode_match_ind_tristate": "true",
          "valid_ind_tristate": "true"
        }
      ],
      "image_list": [
        {
          "image_name": "Portrait 1",
          "base64_image": "<base64_portrait>"
        },
        {
          "image_name": "Document 1",
          "base64_image": "<base64_doc_image>"
        }
      ]
    }
  },
  "result": true,
  "result_code": {
    "name": "Success",
    "id": 0
  },
  "Status": "Success",
  "Message": "Message"
}

​
Comparison Field List

Each entry in comparison_field_list validates a specific field on the document:
FieldDescription
field_nameThe data field being validated (e.g. DOCUMENT_NUMBER, DATE_OF_BIRTH)
visual_zone_valueValue read from the printed/visual zone of the document
barcode_valueValue read from the document barcode
mrz_valueValue read from the Machine Readable Zone (for passports)
visual_barcode_match_ind_tristate"true" if visual and barcode values match
valid_ind_tristate"true" if this field passes validation

​
Tristate Values

Match indicators use tristate values: "true", "false", or "" (not applicable).