> For the complete documentation index, see [llms.txt](https://developer.fraudcheck.co.za/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.fraudcheck.co.za/identity/asylum-seeker-refugee-verification.md).
# Asylum Seeker / Refugee Verification
Asylum Seeker/Refugee Status Verification confirms a refugee's NIIS (National Immigration Information System) file number and permit details against official immigration records. A single synchronous request returns the verified personal information, file and permit status, a risk assessment, and the official facial image where available.
## When to use this
Use this service to:
* Verify the authenticity of a refugee's NIIS file number and permit
* Confirm permit status and expiry date during onboarding
* Retrieve the official facial image for KYC documentation
* Apply a risk assessment to refugee applicants for AML/KYC workflows
## How it works
Submit the NIIS file number along with the refugee's name and cell number in a single POST request. The service matches the details against official records and returns biographic data, file and permit details, a name-match outcome, a risk assessment, and (if available) a base64-encoded facial image. Results are returned synchronously and can also be re-fetched later by transaction ID.
| Property | Value |
| --------------------- | ----------------------------------------------------------------------------- |
| Response type | `Synchronous` |
| Typical response time | 2–5s |
| Result retrieval | Returned inline; also retrievable via `GET /refugee/results/{transaction_id}` |
| Consent required | `Yes` (mandatory) |
| Region | South Africa |
## Authentication
```http
Authorization: Bearer {your_access_token}
```
## Endpoints
```http
POST /refugee/verify
GET /refugee/results/{transaction_id}
GET /refugee/summary/{transaction_id}
```
## Request
### Headers
| Header | Required | Value |
| --------------- | -------- | ------------------ |
| `Authorization` | Yes | `Bearer {token}` |
| `Content-Type` | Yes | `application/json` |
### Body parameters
| Field | Type | Required | Description |
| ------------------------------ | ------- | -------- | ------------------------------------------ |
| `IdentityNo` | string | Yes | NIIS file number (e.g. `TPAW223232323ssd`) |
| `FirstName` | string | Yes | Refugee's first name |
| `LastName` | string | Yes | Refugee's surname |
| `CellNo` | string | Yes | Cell phone number |
| `ConsentObtainedByDataSubject` | boolean | Yes | Must be `true`. Confirms POPIA consent. |
| `SecondName` | string | No | Middle name |
| `EmailAddress` | string | No | Email address |
### Example request
```json
{
"IdentityNo": "TPAW223232323ssd",
"FirstName": "JOHN",
"LastName": "DOE",
"SecondName": "GOWERO",
"CellNo": "0602223333",
"EmailAddress": "john.doe@email.com",
"ConsentObtainedByDataSubject": true
}
```
## Response
### Response fields
| Field | Type | Description |
| ------------------------ | ------- | -------------------------------------------------------------------- |
| `transaction_id` | string | Unique identifier for this verification |
| `niis_file_number` | string | NIIS file number submitted |
| `is_success` | boolean | Whether the request completed successfully |
| `is_verified` | boolean | Whether the refugee record was verified |
| `outcome` | string | `MATCH`, `PARTIAL_MATCH`, or `NO_MATCH` |
| `screening_result` | string | `ACCEPT` or `REJECT` |
| `full_name` | string | Full name from official records |
| `first_name` | string | First name from records |
| `last_name` | string | Surname from records |
| `date_of_birth` | string | Date of birth (`YYYY-MM-DD`) |
| `gender` | string | `M`, `F`, or `X` |
| `age` | integer | Age in years |
| `country` | string | Country of origin |
| `nationality` | string | Nationality |
| `office_of_application` | string | Immigration office that processed the application |
| `file_status` | string | `APPROVED`, `PENDING`, `REJECTED`, `WITHDRAWN`, `EXPIRED`, `UNKNOWN` |
| `permit_number` | string | Refugee permit number |
| `permit_expiry_date` | string | Permit expiry date (`YYYY-MM-DD`) |
| `refugee_id_number` | string | Unique refugee ID |
| `first_name_result` | string | Name match: `Match`, `Partial`, or `No Match` |
| `last_name_result` | string | Surname match: `Match`, `Partial`, or `No Match` |
| `refugee_risk_outcome` | string | `LOW_RISK`, `MEDIUM_RISK`, `HIGH_RISK`, or `UNKNOWN` |
| `facial_image_available` | boolean | Whether a facial image was returned |
| `facial_image` | string | Base64-encoded JPEG/PNG facial image |
| `ds_status` | string | Data source status (`Success`, `Failure`, etc.) |
| `ds_message` | string | Human-readable status message |
### Example response - verified
```json
{
"transaction_id": "d41d8cd98f00b204e9800998ecf8427e",
"niis_file_number": "TPAW223232323ssd",
"is_success": true,
"is_verified": true,
"outcome": "MATCH",
"screening_result": "ACCEPT",
"full_name": "JOHN DOE",
"first_name": "JOHN",
"last_name": "DOE",
"date_of_birth": "1985-06-15",
"gender": "M",
"age": 39,
"country": "Zimbabwe",
"nationality": "Zimbabwean",
"office_of_application": "Johannesburg",
"file_status": "APPROVED",
"permit_number": "ZW/001/2020/12345",
"permit_expiry_date": "2025-12-31",
"refugee_id_number": "RID123456789",
"first_name_result": "Match",
"last_name_result": "Match",
"refugee_risk_outcome": "LOW_RISK",
"facial_image_available": true,
"facial_image": "base64_encoded_image_data...",
"ds_status": "Success",
"ds_message": "Record found and verified"
}
```
## Retrieving results later
Re-fetch a previously completed verification by transaction ID:
```http
GET /refugee/results/{transaction_id}
```
For a lightweight summary (verification status, risk outcome, screening result, and timestamp only):
```http
GET /refugee/summary/{transaction_id}
```
### Example summary response
```json
{
"transaction_id": "d41d8cd98f00b204e9800998ecf8427e",
"niis_file_number": "TPAW223232323ssd",
"is_verified": true,
"ds_status": "Success",
"ds_message": "Record found and verified",
"refugee_risk_outcome": "LOW_RISK",
"screening_result": "ACCEPT",
"created_at": "2026-01-14T10:30:00Z"
}
```
## Errors
| HTTP | Code | Meaning | Action |
| ---- | --------------------- | ------------------------------------------------------------------- | ----------------------------------------------------- |
| 401 | `unauthorized` | Token missing or expired | Refresh your access token |
| 403 | `forbidden` | Account lacks access to this service | Contact your account manager |
| 422 | `invalid_input` | Required field missing or `ConsentObtainedByDataSubject` not `true` | Provide all required fields and set consent to `true` |
| 502 | `service_unavailable` | Upstream service temporarily unavailable | Retry with exponential backoff |
| 500 | `server_error` | Unexpected error | Contact support |
## Code examples
{% tabs %}
{% tab title="cURL" %}
```bash
BASE_URL="https://consumer-service-api.fraudcheckonline.co.za/consumer-service"
curl -X POST "$BASE_URL/refugee/verify" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"IdentityNo": "TPAW223232323ssd",
"FirstName": "LEONARD",
"LastName": "NAYUCHI",
"CellNo": "0652411321",
"ConsentObtainedByDataSubject": true
}'
```
{% endtab %}
{% tab title="Python" %}
```python
import base64, requests
BASE_URL = "https://consumer-service-api.fraudcheckonline.co.za/consumer-service"
response = requests.post(
f"{BASE_URL}/refugee/verify",
headers={
"Authorization": f"Bearer {access_token}",
"Content-Type": "application/json",
},
json={
"IdentityNo": "TPAW223232323ssd",
"FirstName": "LEONARD",
"LastName": "NAYUCHI",
"CellNo": "0652411321",
"ConsentObtainedByDataSubject": True,
},
)
data = response.json()
print(f"Verified: {data['is_verified']}")
print(f"File status: {data['file_status']}")
print(f"Permit expires: {data['permit_expiry_date']}")
print(f"Risk: {data['refugee_risk_outcome']}")
if data.get("facial_image_available"):
with open("refugee_photo.jpg", "wb") as f:
f.write(base64.b64decode(data["facial_image"]))
```
{% endtab %}
{% tab title="JavaScript (Node.js)" %}
```javascript
const BASE_URL = "https://consumer-service-api.fraudcheckonline.co.za/consumer-service";
const response = await fetch(`${BASE_URL}/refugee/verify`, {
method: "POST",
headers: {
Authorization: `Bearer ${accessToken}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
IdentityNo: "TPAW223232323ssd",
FirstName: "LEONARD",
LastName: "NAYUCHI",
CellNo: "0652411321",
ConsentObtainedByDataSubject: true,
}),
});
const data = await response.json();
console.log(`Verified: ${data.is_verified}`);
console.log(`Risk: ${data.refugee_risk_outcome}`);
```
{% endtab %}
{% endtabs %}
## Reference values
### `file_status`
| Value | Meaning |
| ----------- | --------------------------- |
| `APPROVED` | Refugee status approved |
| `PENDING` | Application pending review |
| `REJECTED` | Application rejected |
| `WITHDRAWN` | Application withdrawn |
| `EXPIRED` | Permit or status expired |
| `UNKNOWN` | Status cannot be determined |
### `refugee_risk_outcome`
| Value | Meaning |
| ------------- | -------------------------------------------------- |
| `LOW_RISK` | No significant risk indicators |
| `MEDIUM_RISK` | Some concerning factors; manual review recommended |
| `HIGH_RISK` | Multiple risk factors detected |
| `UNKNOWN` | Risk assessment inconclusive |
### Name match results
`Match` - exact match with official records. `Partial` - minor variation. `No Match` - does not match.
## Compliance & consent
* Consent is mandatory. Requests without `ConsentObtainedByDataSubject: true` are rejected.
* Obtain explicit consent from the data subject before submitting.
* Retain proof of consent and any retrieved facial images in line with POPIA requirements.
## FAQ
What format is the facial image?
A base64-encoded JPEG or PNG returned in the `facial_image` field. Decode it to obtain the binary image. Only present when `facial_image_available` is `true`.
What does a `MEDIUM_RISK` or `HIGH_RISK` outcome mean?
The record has indicators that warrant additional review. Treat these as a signal to route the applicant to manual KYC review rather than auto-approval.
Can I verify an expired permit?
Yes. The service will return `file_status: "EXPIRED"` along with the original permit details so you can take an appropriate action.
What client timeout should I configure?
Up to 60 seconds.
## Changelog
| Date | Version | Change |
| ---------- | ------- | ---------------- |
| 2026-04-11 | v1.0 | Initial release. |