Validate RSA ID Document

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

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,
    "SCConsentReceived": true,
    "RsaIdNumber": "8001014800080",
    "IdentityDocumentType": "NEW_ID_CARD",
    "IdImageFront": "<base64_front_of_id>",
    "IdImageBack": "<base64_back_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,
    "SCConsentReceived": true,
    "RsaIdNumber": "8001014800080",
    "IdentityDocumentType": "NEW_ID_CARD",
    "IdImageFront": "<base64_front_of_id>",
    "IdImageBack": "<base64_back_of_id>",
    "FaceString": "<base64_selfie>",
    "CRef": "REF00001"
  }'

Validate RSA ID Document + Photo + Liveness

POST /Citizen/ValidateRSAIDDocAndPhotoWithLiveness

Full validation: document authenticity + face match + liveness detection. The request body is the same as for ValidateRSAIDDocAndPhoto.

curl -X POST "https://citizen.uat.securecitizen.cloud/Citizen/ValidateRSAIDDocAndPhotoWithLiveness" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "ConsentReceived": true,
    "SCConsentReceived": true,
    "RsaIdNumber": "8001014800080",
    "IdentityDocumentType": "NEW_ID_CARD",
    "IdImageFront": "<base64_front_of_id>",
    "IdImageBack": "<base64_back_of_id>",
    "FaceString": "<base64_selfie>",
    "CRef": "REF00001"
  }'

Request Fields

All three endpoints share these fields. FaceString applies only to the photo and liveness tiers.

Field	Type	Required	Description
`ConsentReceived`	boolean	Yes	Must be `true`. Confirms you have the subject’s consent to process their personal information
`SCConsentReceived`	boolean	Yes	Confirms you have the subject’s consent for the platform to store their data
`RsaIdNumber`	string	Yes	ID number as it appears on the document
`IdentityDocumentType`	string	Yes	Document type: `GREEN_ID` or `NEW_ID_CARD`
`IdImageFront`	string	Yes	Base64-encoded image of the front of the ID
`IdImageBack`	string	No	Base64-encoded image of the back of the ID
`FaceString`	string	Conditional	Base64-encoded selfie. Required for `ValidateRSAIDDocAndPhoto` and `ValidateRSAIDDocAndPhotoWithLiveness`
`MobileNumber`	string	No	Subject’s mobile number (`0xxx` format)
`EmailAddress`	string	No	Subject’s email address
`RefNo`	string	No	Reference number
`CRef`	string	No	Your transaction reference

Response

All three endpoints return the document validation result:

{
  "response_object": {
    "ocr_result": {
      "document_number": "8001014800080",
      "validation_passed": "valid",
      "comparison_field_list": [
        {
          "field_name": "DOCUMENT_NUMBER",
          "mrz_value": null,
          "visual_zone_value": "8001014800080",
          "barcode_value": "8001014800080",
          "mrz_visual_match_ind_tristate": "",
          "visual_barcode_match_ind_tristate": "true",
          "mrz_barcode_match_ind_tristate": "",
          "valid_ind_tristate": "true"
        },
        {
          "field_name": "DATE_OF_BIRTH",
          "mrz_value": null,
          "visual_zone_value": "1980-01-01",
          "barcode_value": "1980-01-01",
          "mrz_visual_match_ind_tristate": "",
          "visual_barcode_match_ind_tristate": "true",
          "mrz_barcode_match_ind_tristate": "",
          "valid_ind_tristate": "true"
        },
        {
          "field_name": "SURNAME",
          "mrz_value": null,
          "visual_zone_value": "DOE",
          "barcode_value": null,
          "mrz_visual_match_ind_tristate": "",
          "visual_barcode_match_ind_tristate": "",
          "mrz_barcode_match_ind_tristate": "",
          "valid_ind_tristate": "true"
        }
      ],
      "image_list": [
        {
          "image_name": "Portrait 1",
          "base64_image": "<base64_portrait>",
          "document_category": null,
          "document_type": null,
          "raw_mrz": null,
          "authenticity_check_list": null
        },
        {
          "image_name": "Document 1",
          "base64_image": "<base64_doc_image>",
          "document_category": null,
          "document_type": null,
          "raw_mrz": null,
          "authenticity_check_list": null
        }
      ]
    }
  },
  "result": true,
  "result_code": {
    "name": "Success",
    "id": 0
  },
  "CRef": "REF00001",
  "Status": "Success",
  "Message": "Message"
}

Field	Description
`result`	`true` if the validation succeeded
`result_code`	Result `name` and numeric `id`
`response_object.ocr_result.document_number`	Document number read from the ID
`response_object.ocr_result.validation_passed`	Overall validation outcome, for example `valid`
`response_object.ocr_result.image_list`	Images extracted from the document, such as the portrait
`CRef`	The transaction reference you supplied

Comparison Field List

Each entry in comparison_field_list validates a specific field on the document:

Field	Description
`field_name`	The data field being validated (e.g. `DOCUMENT_NUMBER`, `DATE_OF_BIRTH`)
`visual_zone_value`	Value read from the printed/visual zone of the document
`barcode_value`	Value read from the document barcode
`mrz_value`	Value read from the Machine Readable Zone (for passports)
`visual_barcode_match_ind_tristate`	`"true"` if visual and barcode values match
`mrz_visual_match_ind_tristate`	`"true"` if MRZ and visual values match
`mrz_barcode_match_ind_tristate`	`"true"` if MRZ 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).

Photo and Liveness Fields

The photo and liveness tiers add fields to the top level of the response:

ValidateRSAIDDocAndPhoto adds FaceResult.
ValidateRSAIDDocAndPhotoWithLiveness adds FaceResult, LivenessResult, and IsWalletCreated.

{
  "FaceResult": {
    "isIdentical": true,
    "confidence": 0.98
  },
  "LivenessResult": {
    "LivenessResultScore": 1,
    "LivenessResultProbability": 0.8,
    "LivenessResultQuality": 0.8,
    "LivenessResultClass": false,
    "LivenessPassResult": true,
    "LivenessMessage": "Liveness check successful"
  },
  "IsWalletCreated": false
}

Field	Description
`FaceResult.isIdentical`	Whether the selfie matches the face on the document
`FaceResult.confidence`	Confidence score of the face match
`LivenessResult.LivenessPassResult`	`true` if the liveness check passed
`IsWalletCreated`	`true` only when all validations pass and a wallet is created

See Face Compare for the full list of liveness result fields.

Identity Verification

Biometrics

Compliance & Screening

Financial Verification

Enterprise

Validate RSA ID Document

Overview

Document Only

Document + Photo

Document + Photo + Liveness

Validate RSA ID Document

Validate RSA ID Document + Photo

Validate RSA ID Document + Photo + Liveness

Request Fields

Response

Comparison Field List

Tristate Values

Photo and Liveness Fields

​Overview

Document Only

Document + Photo

Document + Photo + Liveness

​Validate RSA ID Document

​Validate RSA ID Document + Photo

​Validate RSA ID Document + Photo + Liveness

​Request Fields

​Response

​Comparison Field List

​Tristate Values

​Photo and Liveness Fields

Overview

Validate RSA ID Document

Validate RSA ID Document + Photo

Validate RSA ID Document + Photo + Liveness

Request Fields

Response

Comparison Field List

Tristate Values

Photo and Liveness Fields