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

# Refugee Verification

> Verify refugee documents against the National Immigration Information System (NIIS).

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

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

| Field               | Type    | Required    | Description                                                     |
| ------------------- | ------- | ----------- | --------------------------------------------------------------- |
| `ConsentReceived`   | boolean | **Yes**     | Must be `true`                                                  |
| `FileNumber`        | string  | **Yes**     | Refugee NIIS file 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 selfie. Required if `FirstNames`/`LastName` not provided |
| `LivenessRequired`  | boolean | No          | Run a liveness check on the provided selfie                     |
| `NIISImageRequired` | boolean | No          | Return the subject's photo from NIIS                            |
| `CRef`              | string  | No          | Your transaction reference                                      |
| `Subsidiary`        | string  | No          | 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": "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

| Field                                | Description                                        |
| ------------------------------------ | -------------------------------------------------- |
| `firstNameResult` / `lastNameResult` | Similarity score (0–100) vs NIIS record            |
| `niisFileNumber`                     | Confirmed NIIS file number                         |
| `fileStatus`                         | Current status of the refugee file                 |
| `permitNumber`                       | Associated permit number                           |
| `expiryDate`                         | Permit expiry date                                 |
| `refugeeIDNumber`                    | Refugee ID number                                  |
| `facialImage`                        | Base64 NIIS photo (if `NIISImageRequired: true`)   |
| `FaceResult.isIdentical`             | Whether the provided selfie matches the NIIS photo |
| `LivenessResult.LivenessPassResult`  | `true` if liveness check passed                    |