Appearance
Create Face Match Request
To initiate a verification, you can submit the customer's selfie alongside their National Identification Number (NIN) to cross-reference with the authority’s records. Please note that these requests are queued and processed asynchronously.
Endpoints
| Environment | URL |
|---|---|
| Sandbox | https://api-test.streamline.laboremus.ug/idv/api/identities/biometrics/match?v=2.0 |
| Production | https://api.streamline.laboremus.ug/idv/api/identities/biometrics/match?v=2.0 |
Request
Request Type: POST
Authorization
All requests must be authenticated using OAuth 2.0 Client Credentials. Follow the steps in the Authentication section to obtain an access token.
Request Body(multipart/form-data)
| Name | Type | Required | Description |
|---|---|---|---|
| externalReference | string | No | Your reference ID to track this request |
| selfie | File (png, jpeg, jpg) | Yes | Selfie image of the person to verify |
| nin | string | No | NIN of the individual used to match against the authority photo instead of targetImage |
File Requirements
Images must be sent as multipart/form-data. Maximum file size is 5 MB per image.
Example Request (Image vs Image)
Content-Type
multipart/form-data
bash
curl --request POST \
--url 'https://api.streamline.laboremus.ug/idv/api/identities/biometrics/match?v=2.0' \
--header 'Authorization: Bearer <access_token>' \
--form 'sourceImage=@selfie.jpg' \
--form 'targetImage=@id_front.jpg' \
--form 'externalReference=my-ref-12345'curl --request POST \
--url 'https://api.streamline.laboremus.ug/idv/api/identities/biometrics/match?v=2.0' \
--header 'Authorization: Bearer <access_token>' \
--form 'sourceImage=@selfie.jpg' \
--form 'targetImage=@id_front.jpg' \
--form 'externalReference=my-ref-12345'Example Request (NIN + Selfie)
Content-Type
multipart/form-data
bash
curl --request POST \
--url 'https://api.xxxxx.ug/idv/api/identities/biometrics/match?v=2.0' \
--header 'Authorization: Bearer <JWT token>' \
--form 'ExternalReference=461c535e-0dbd-4e27-b223-e6386f6dc635' \
--form 'Nin=CM9400810629JH' \
--form 'Selfie=@/path/to/selfie.jpg'curl --request POST \
--url 'https://api.xxxxx.ug/idv/api/identities/biometrics/match?v=2.0' \
--header 'Authorization: Bearer <JWT token>' \
--form 'ExternalReference=461c535e-0dbd-4e27-b223-e6386f6dc635' \
--form 'Nin=CM9400810629JH' \
--form 'Selfie=@/path/to/selfie.jpg'Response
A successful request returns a 202 Accepted status with details to track the face match processing.
Response Fields
| Name | Type | Description |
|---|---|---|
| id | string | Unique identifier for this request |
| requestUri | string or null | URL to retrieve the request status and results |
| status | string (Enum: Pending, Completed, Failed) | Current processing status of the request |
| externalReference | string or null | Your reference ID if provided in the request |
Example Response
Content-Type
application/json
json
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"requestUri": "/idv/api/identities/biometrics/match/497f6eca-6276-4993-bfeb-53cbbbba6f08",
"status": "Pending",
"externalReference": "my-ref-12345"
}{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"requestUri": "/idv/api/identities/biometrics/match/497f6eca-6276-4993-bfeb-53cbbbba6f08",
"status": "Pending",
"externalReference": "my-ref-12345"
}Next Steps
Use the id or requestUri to poll for results using the Get Facematch Details endpoint.
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 |