Appearance
Get NIRA Identity Retrieval Details
Retrieve the results of a previously submitted identity verification request to retrieve National ID identity information. Poll this endpoint until requestStatus is Completed or Failed.
Polling Recommendation
Poll every 2–5 seconds. Do not poll more frequently than once per second.
Endpoints
| Environment | URL |
|---|---|
| Sandbox | https://api-test.streamline.laboremus.ug/idv/api/identities/{id}?v=2.0 |
| Production | https://api.streamline.laboremus.ug/idv/api/identities/{id}?v=2.0 |
Sandbox testing
See the Sandbox Context page for NIN formats and whitelisted test values.
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 in the 202 response from the Submit endpoint |
Example Request
bash
curl --request GET \
--url 'https://api.streamline.laboremus.ug/idv/api/identities/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/019a0100-146a-7237-a47f-8ae09dbabed6?v=2.0' \
--header 'Authorization: Bearer <access_token>'Response
A successful request returns a 200 OK with the identity retrieval 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 customer National Identity Number |
| result | object | The identity retrieval result details (see below) |
| initiator | string or null | Name of the user who initiated the request |
| initiatorId | string | Unique identifier of the initiating user |
| receivedAt | string | ISO 8601 timestamp when the request was received |
| completedAt | string | ISO 8601 timestamp when processing completed |
| requestStatus | string | Processing status: Pending, Completed, or Failed |
Result Object
| Name | Type | Description |
|---|---|---|
| surname | boolean | true if faces match, false otherwise |
| givenNames | number | Raw similarity score (0 to 1) |
| dateOfBirth | string | Similarity score as a percentage |
| livingStatus | string | Status of the individual (Alive/Deceased) |
| gender | string | Sex of the individual (Male/Female) |
| 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"
}{
"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"
}Error Response
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 |
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 |
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 |
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 |
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 |