Create National ID Verification Requests.

Accepts requests for verifying Ugandan National ID details. All requests are queued and processed as soon as possible.

Endpoints

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

Request

Request Type : POST

Authorization

This API uses OAuth 2.0 Client Credentials grant for authentication. You must obtain an access token from the authorization server before making API requests.

Obtaining an Access Token

Make a POST request to the token endpoint with your client credentials:

Token Endpoint: https://auth-api-demo.streamline.laboremus.ug/realms/streamline-test-realm/protocol/openid-connect/token

cURLJavaScriptPython

bash

curl --request POST \
  --url https://auth-api-demo.streamline.laboremus.ug/realms/streamline-test-realm/protocol/openid-connect/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'client_id=YOUR_CLIENT_ID' \
  --data 'client_secret=YOUR_CLIENT_SECRET' \
  --data 'grant_type=client_credentials'

curl --request POST \
  --url https://auth-api-demo.streamline.laboremus.ug/realms/streamline-test-realm/protocol/openid-connect/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'client_id=YOUR_CLIENT_ID' \
  --data 'client_secret=YOUR_CLIENT_SECRET' \
  --data 'grant_type=client_credentials'

const response = await fetch(
  'https://auth-api-demo.streamline.laboremus.ug/realms/streamline-test-realm/protocol/openid-connect/token',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
    },
    body: new URLSearchParams({
      client_id: 'YOUR_CLIENT_ID',
      client_secret: 'YOUR_CLIENT_SECRET',
      grant_type: 'client_credentials',
    }),
  }
)

const { access_token } = await response.json()

const response = await fetch(
  'https://auth-api-demo.streamline.laboremus.ug/realms/streamline-test-realm/protocol/openid-connect/token',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
    },
    body: new URLSearchParams({
      client_id: 'YOUR_CLIENT_ID',
      client_secret: 'YOUR_CLIENT_SECRET',
      grant_type: 'client_credentials',
    }),
  }
)

const { access_token } = await response.json()

python

import requests

response = requests.post(
    'https://auth-api-demo.streamline.laboremus.ug/realms/streamline-test-realm/protocol/openid-connect/token',
    data={
        'client_id': 'YOUR_CLIENT_ID',
        'client_secret': 'YOUR_CLIENT_SECRET',
        'grant_type': 'client_credentials',
    }
)

access_token = response.json()['access_token']

import requests

response = requests.post(
    'https://auth-api-demo.streamline.laboremus.ug/realms/streamline-test-realm/protocol/openid-connect/token',
    data={
        'client_id': 'YOUR_CLIENT_ID',
        'client_secret': 'YOUR_CLIENT_SECRET',
        'grant_type': 'client_credentials',
    }
)

access_token = response.json()['access_token']

Token Response

json

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 300,
  "token_type": "Bearer"
}

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 300,
  "token_type": "Bearer"
}

Using the Access Token

Include the token in the Authorization header for all API requests:

Authorization: Bearer <access_token>

Authorization: Bearer <access_token>

Token Expiration

Access tokens expire after the duration specified in expires_in (in seconds). Request a new token when the current one expires.

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());

Query Parameters

Name	Type	Required	Description
v	string	no	The API Version

Request Body

Name	Type	Required	Description
surname	string or null	no*	Surname on the card
givenNames	string or null	no*	Given names on the card
otherNames	string or null	no	Other names on the card
dateOfBirth	string(date)	no*	Date of birth on the card
nin	string(14)	yes	National ID Number on the card
cardNumber	string(9)	yes	Card number of the card

INFO

One of the 3 surname, givenNames and dateOfBirth is needed to make this verification

Example Request Body

Content type

application/json

json

{
    "surname": "string",
    "givenNames": "string",
    "otherNames": "string",
    "dateOfBirth": "2019-08-24",
    "nin": "string",
    "cardNumber": "string"
}

{
    "surname": "string",
    "givenNames": "string",
    "otherNames": "string",
    "dateOfBirth": "2019-08-24",
    "nin": "string",
    "cardNumber": "string"
}

Response

Response Values

Name	Type	Description
id	string	Unique Id of the request
requestUri	string or null	The Url to find the request
status	string (Enum: `Pending`, `Completed`, `Failed`)	The stage of processing at which the request is

Example Response Body

Content type

application/json

json

{
   "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
   "requestUri": "string",
   "status": "Pending"
}

{
   "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
   "requestUri": "string",
   "status": "Pending"
}

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

V1

V2

V1

V2

V1

V2

V1

V2

Photo match

V1

V2

V3

V1

V2

V1

V2

V3

V1

V2

Person

Company

Create National ID Verification Requests. ​

Endpoints ​

Request ​

Request Type : POST ​

Authorization ​

Obtaining an Access Token ​

Token Response ​

Using the Access Token ​

Subscription Key ​

Query Parameters ​

Request Body ​

Example Request Body ​

Response ​

Response Values ​

Example Response Body ​

Error Response ​

errors ​

Error ​

Error ​

Error ​

Error ​

Create National ID Verification Requests.

Endpoints

Request

Request Type : POST

Authorization

Obtaining an Access Token

Token Response

Using the Access Token

Subscription Key

Query Parameters

Request Body

Example Request Body

Response

Response Values

Example Response Body

Error Response

errors

Error

Error

Error

Error