> ## 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.

# RSA ID Verification

> Verify a South African ID number against the Department of Home Affairs with optional biometrics and SAFPS checks.

## 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

```bash theme={null}
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

```json theme={null}
{
  "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:

```json theme={null}
"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 |