Appearance
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/identities/biometrics{id}?v=2.0 |
| Production | https://api.streamline.laboremus.ug/idv/api/identities/biometrics/{id}?v=2.0 |
Request
Request Type: GET
Authorization
Follow steps in the Authorization section to obtain an access token
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | The unique identifier returned when creating the request |
Example Request
bash
curl --request GET \
--url 'https://api.streamline.laboremus.ug/idv/api/identities/biometrics/019a0100-146a-7237-a47f-8ae09dbabed6?v=2.0' \
--header 'Authorization: Bearer <access_token>'curl --request GET \
--url 'https://api.streamline.laboremus.ug/idv/api/identities/biometrics/019a0100-146a-7237-a47f-8ae09dbabed6?v=2.0' \
--header 'Authorization: Bearer <access_token>'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 |