Get Face Match Request Details

Retrieve the results of a previously submitted face match or biometric match request. Use this endpoint to check the processing status and view the match results once completed.

Endpoints

Environment	URL
Sandbox	`https://api-test.streamline.laboremus.ug/idv/api/facematches/{id}?v=2.0`
Production	`https://api.streamline.laboremus.ug/idv/api/facematches/{id}?v=2.0`

Request

Request Type: GET

Authorization

Follow steps in the Authorization section to obtain an access token

INFO

Always add your Subscription key to the request.

Subscription Key

Include your subscription key in every request using one of these methods:

Method	Header/Parameter
Header (recommended)	`Ocp-Apim-Subscription-Key: <your_key>`
Query parameter	`?subscription-key=<your_key>`

bash

curl --request POST \
  --url 'https://api.example.com/endpoint' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Ocp-Apim-Subscription-Key: <your_subscription_key>' \
  --header 'Content-Type: application/json' \
  --data '{"key": "value"}'

curl --request POST \
  --url 'https://api.example.com/endpoint' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Ocp-Apim-Subscription-Key: <your_subscription_key>' \
  --header 'Content-Type: application/json' \
  --data '{"key": "value"}'

const response = await fetch(API_ENDPOINT, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Ocp-Apim-Subscription-Key': '<your_subscription_key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})

const response = await fetch(API_ENDPOINT, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Ocp-Apim-Subscription-Key': '<your_subscription_key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})

python

import requests

response = requests.post(
    API_ENDPOINT,
    headers={
        'Authorization': f'Bearer {access_token}',
        'Ocp-Apim-Subscription-Key': '<your_subscription_key>',
        'Content-Type': 'application/json'
    },
    json=data
)

import requests

response = requests.post(
    API_ENDPOINT,
    headers={
        'Authorization': f'Bearer {access_token}',
        'Ocp-Apim-Subscription-Key': '<your_subscription_key>',
        'Content-Type': 'application/json'
    },
    json=data
)

csharp

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", accessToken);
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "<your_subscription_key>");

var content = new StringContent(
    JsonSerializer.Serialize(data),
    Encoding.UTF8,
    "application/json"
);

var response = await client.PostAsync(API_ENDPOINT, content);

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", accessToken);
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "<your_subscription_key>");

var content = new StringContent(
    JsonSerializer.Serialize(data),
    Encoding.UTF8,
    "application/json"
);

var response = await client.PostAsync(API_ENDPOINT, content);

java

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create(API_ENDPOINT))
    .header("Authorization", "Bearer " + accessToken)
    .header("Ocp-Apim-Subscription-Key", "<your_subscription_key>")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create(API_ENDPOINT))
    .header("Authorization", "Bearer " + accessToken)
    .header("Ocp-Apim-Subscription-Key", "<your_subscription_key>")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

Path Parameters

Name	Type	Required	Description
id	string	Yes	The unique identifier returned when creating the request

Query Parameters

Name	Type	Required	Description
v	string	Yes	API version. Defaults to `1.0`

Example Request

bash

curl --request GET \
  --url 'https://api-test.streamline.laboremus.ug/idv/api/facematches/019a0100-146a-7237-a47f-8ae09dbabed6?v=2.0' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Ocp-Apim-Subscription-Key: <subscription_key>'

curl --request GET \
  --url 'https://api-test.streamline.laboremus.ug/idv/api/facematches/019a0100-146a-7237-a47f-8ae09dbabed6?v=2.0' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Ocp-Apim-Subscription-Key: <subscription_key>'

Response

A successful request returns a 200 OK with the face match results.

Response Fields

Name	Type	Description
id	string	Unique identifier for this request
externalReference	string or null	Your reference ID if provided when creating the request
nin	string or null	The NIN submitted for verification (if applicable)
result	object	The face match result details (see below)
sourceImage	string	Identifier for the uploaded selfie image
targetImage	string	Identifier for the uploaded ID document image
initiator	string or null	Name of the user who initiated the request
initiatorId	string	Unique identifier of the initiating user
tenantId	UUID	Identifier of the tenant that owns this request
receivedAt	string	ISO 8601 timestamp when the request was received
completedAt	string	ISO 8601 timestamp when processing completed
lastUpdated	datetime	ISO 8601 timestamp of the most recent status change
verifiedAt	datetime	ISO 8601 timestamp when the match was completed
requestStatus	string	Processing status: `Pending`, `Completed`, or `Failed`

Result Object

Name	Type	Description
match	boolean	`true` if faces match, `false` otherwise
isMatch	boolean	`true` if the selfie matches the authority photo; `false` otherwise
score	number	Raw similarity score (0 to 1)
percentageScore	string	Similarity score as a percentage
status	string	Verification outcome: `approved` or `declined`
comment	string	Human-readable explanation of the result
files	array	Internal file paths for the processed images
isError	boolean or null	`true` if an error occurred during processing
errorMessage	string or null	Error details if processing failed

Example Response

Content-Type

application/json

json

{
  "id": "019a0100-146a-7237-a47f-8ae09dbabed6",
  "externalReference": null,
  "result": {
    "surname": "Tipiyai",
    "givenNames": "Johnson",
    "dateOfBirth": "1993-01-01",
    "livingStatus": "alive",
    "Gender": "Female",
    "isError": null,
    "errorMessage": null
  },
  "nin": "CM930121003EGE",
  "initiator": null,
  "initiatorId": "67391f12-f75e-419b-8232-f8ea178c93b5",
  "receivedAt": "2025-10-20T09:42:53.728838",
  "completedAt": "2025-10-20T09:43:32.797186",
  "requestStatus": "Completed"
}

::: info Notes
The "result" object contains the verified identity information returned by NIRA.
:::

## Error Response
::: danger  400 The request data is invalid
application/json
:::
| Name    | Type           | Description                                          |
| ------- | -------------- | ---------------------------------------------------- |
| type    | string or null | Type of error response                               |
| title   | string or null | The title of the error response                      |
| status  | integer(int32) | The status of the error response                     |
| traceId | string or null | The traceId of the error request producing the error |
| errors  | object         | Object defining the errors                           |
#### errors
| Name     | Type             | Description                  |
| -------- | ---------------- | ---------------------------- |
| property | Array of strings | The definition of the errors |


::: danger  401 Not authorized to access the endpoint
application/json
:::
| Name  | Type          | Description            |
| ----- | ------------- | ---------------------- |
| error | object(Error) | Type of error response |
#### Error
| Name    | Type           | Description       |
| ------- | -------------- | ----------------- |
| code    | string or null | The Error code    |
| message | string or null | The Error message |


::: danger  403 Refuse to authorize access to the endpoint
application/json
:::
| Name  | Type          | Description            |
| ----- | ------------- | ---------------------- |
| error | object(Error) | Type of error response |
#### Error
| Name    | Type           | Description       |
| ------- | -------------- | ----------------- |
| code    | string or null | The Error code    |
| message | string or null | The Error message |


::: danger  404 Request does not exist
application/json
:::
| Name  | Type          | Description            |
| ----- | ------------- | ---------------------- |
| error | object(Error) | Type of error response |
#### Error
| Name    | Type           | Description       |
| ------- | -------------- | ----------------- |
| code    | string or null | The Error code    |
| message | string or null | The Error message |


::: danger  500 The server encountered an unexpected error
application/json
:::
| Name  | Type          | Description            |
| ----- | ------------- | ---------------------- |
| error | object(Error) | Type of error response |
#### Error
| Name    | Type           | Description       |
| ------- | -------------- | ----------------- |
| code    | string or null | The Error code    |
| message | string or null | The Error message |

{
  "id": "019a0100-146a-7237-a47f-8ae09dbabed6",
  "externalReference": null,
  "result": {
    "surname": "Tipiyai",
    "givenNames": "Johnson",
    "dateOfBirth": "1993-01-01",
    "livingStatus": "alive",
    "Gender": "Female",
    "isError": null,
    "errorMessage": null
  },
  "nin": "CM930121003EGE",
  "initiator": null,
  "initiatorId": "67391f12-f75e-419b-8232-f8ea178c93b5",
  "receivedAt": "2025-10-20T09:42:53.728838",
  "completedAt": "2025-10-20T09:43:32.797186",
  "requestStatus": "Completed"
}

::: info Notes
The "result" object contains the verified identity information returned by NIRA.
:::

## Error Response
::: danger  400 The request data is invalid
application/json
:::
| Name    | Type           | Description                                          |
| ------- | -------------- | ---------------------------------------------------- |
| type    | string or null | Type of error response                               |
| title   | string or null | The title of the error response                      |
| status  | integer(int32) | The status of the error response                     |
| traceId | string or null | The traceId of the error request producing the error |
| errors  | object         | Object defining the errors                           |
#### errors
| Name     | Type             | Description                  |
| -------- | ---------------- | ---------------------------- |
| property | Array of strings | The definition of the errors |


::: danger  401 Not authorized to access the endpoint
application/json
:::
| Name  | Type          | Description            |
| ----- | ------------- | ---------------------- |
| error | object(Error) | Type of error response |
#### Error
| Name    | Type           | Description       |
| ------- | -------------- | ----------------- |
| code    | string or null | The Error code    |
| message | string or null | The Error message |


::: danger  403 Refuse to authorize access to the endpoint
application/json
:::
| Name  | Type          | Description            |
| ----- | ------------- | ---------------------- |
| error | object(Error) | Type of error response |
#### Error
| Name    | Type           | Description       |
| ------- | -------------- | ----------------- |
| code    | string or null | The Error code    |
| message | string or null | The Error message |


::: danger  404 Request does not exist
application/json
:::
| Name  | Type          | Description            |
| ----- | ------------- | ---------------------- |
| error | object(Error) | Type of error response |
#### Error
| Name    | Type           | Description       |
| ------- | -------------- | ----------------- |
| code    | string or null | The Error code    |
| message | string or null | The Error message |


::: danger  500 The server encountered an unexpected error
application/json
:::
| Name  | Type          | Description            |
| ----- | ------------- | ---------------------- |
| error | object(Error) | Type of error response |
#### Error
| Name    | Type           | Description       |
| ------- | -------------- | ----------------- |
| code    | string or null | The Error code    |
| message | string or null | The Error message |

V1

V2

V1

V2

V2

V1

V2

V1

V2

Photo match

V1

V2

V3

V1

V2

V1

V2

V3

V1

V2

Person

Company

Get Face Match Request Details ​

Endpoints ​

Request ​

Request Type: GET ​

Authorization ​

Subscription Key ​

Path Parameters ​

Query Parameters ​

Example Request ​

Response ​

Response Fields ​

Result Object ​

Example Response ​