Basic KYC in Uganda

Overview

The Basic KYC API allows you to verify the identity information for an individual using their personal information and the ID number from one of our supported ID Types. This API will return a value of no match, partial match, or exact match along with detailed data of the matching outcome of specific fields.

How Basic KYC in Uganda differs from other countries

When running Basic KYC in Uganda, you are required to send us the NIN as the id_number, the card number as secondary_id_number, date of birth as dob.

	Uganda	Other Countries
Required user inputs	ID Number Secondary ID Number Date of birth	ID Number First Name Last Name
Logic for matching submitted fields	Secondary ID Number and Date of Birth must match exactly	Some margin of user input error allowed for First Name, Last Name, Phone Number, and Date of Birth fields. Read more here<add link to docs> .

Integration Options

Currently only available via the Rest API.

Asynchronous vs Synchronous

This API is available as both an Asynchronous API (recommended) and as a Synchronous API.

The Asynchronous API guarantees an eventual response regardless of ID authority availability. The Synchronous API is suited for real-time environments, such as mobile applications. It does not guarantee a response in the event that an ID authority is unavailable.

For high volume applications the Asynchronous API is required. If you are using the Asynchronous API you must have a callback endpoint in your request where the response will be delivered. The urls for the endpoints are:

Asynchronous

Environment	URL
Sandbox	https://testapi.smileidentity.com/v2/verify_async
Production	https://api.smileidentity.com/v2/verify_async

Synchronous

Environment	URL
Sandbox	https://testapi.smileidentity.com/v2/verify
Production	https://api.smileidentity.com/v2/verify

Request Values

The Basic KYC API has the following input parameters. They should be contained in a JSON body object submitted to the endpoint.

Request Type: Post

Name	Type	Required	Description
source_sdk	string	Yes	The integration option you are using. For rest api send the value as "rest_api"
source_sdk_version	string	Yes	The version of the integration option you are using
partner_id	string	Yes	A unique number assigned by Smile ID to your account. Can be found with your API key here​
signature	string	Yes	The outgoing signature to authenticate the request from you to Smile ID
timestamp	string	Yes	The timestamp used to calculate the signature in ISO date/time format
country	string	Yes	2-letter country code. For Uganda you send value as “UG”
id_type	string	Yes	The ID type you want to query. Set the value as “NATIONAL_ID_NO_PHOTO”
id_number	string	Yes	ID number, you can enforce ID number format using the Uganda National ID regex /^[A-Z0-9]{14}$/i
callback_url	string	Yes (async)	Your callback url, results of jobs will be sent to the specified url. You can read more about callback urls here​
dob	string	Yes	Date of Birth (YYYY-MM-DD)
secondary_id_number	string	Yes	The card number on the document
partner_params	object	Yes	A JSON object containing the partner parameters below as well as any additional key value pairs you wish to include for tracking which will be returned in the response
{ job_id	string	Yes	A value generated by you, so you can track jobs on your end. This value must be unique, can be any string and can follow your identifier convention
user_id}	string	Yes	A value generated by you, so you can track users on your end. This value must be unique, can be any string and can follow your identifier convention.

Example JSON Body

{
  "source_sdk": "rest_api",
  "source_sdk_version": "2.0.0",
  "partner_id": "023",
  "timestamp": "2021-08-12T17:57:00.614879",
  "signature": "...",
  "country": "UG",
  "id_type": "NATIONAL_ID_NO_PHOTO",
  "id_number": "0000000000000",
  "callback_url": "example.webhook.com",
  "secondary_id_number": "000000000",
  "dob": "2000-09-20",
  "partner_params": {
    "job_id": "3ba0e15e-1a56-4799-a94d-b0e084f50256",
    "user_id": "4cb0f26-2b567-5800-b05e-c0f095g6036"
  }
}

Return Values

The Basic KYC API returns a set of top-level values and a detailed set of actions that can be used for a more granular evaluation of the individual fields.

​

Example JSON Response

Depending on the endpoint you hit (asynchronous or synchronous) the immediate response you get is different.

For the Asynchronous Endpoint

{
  "success": true
}

For the Synchronous Endpoint (this is the same response sent to the callback of the asynchronous endpoint)

{
  "SmileJobID": "0000000571",
  "PartnerParams": {
    "job_id": "001",
    "user_id": "UG_Test_User_001",
    "job_type": 5
  },
  "ResultText": "Exact Match",
  "ResultCode": "1020",
  "Actions": {
    "DOB": "Exact Match",
    "Gender": "Not Provided",
    "ID_Verification": "Exact Match",
    "Names": "Not Provided",
    "Phone_Number": "Not Provided",
    "Return_Personal_Info": "Not Applicable",
    "Secondary_ID_Number": "Exact Match",
    "Verify_ID_Number": "Verified"
  },
  "Source": "ID Verification",
  "signature": "...",
  "timestamp": "2022-07-27T21:02:27.384Z"
}

Evaluating the Results

The overall result of the verification can be any of the following:

• Exact match: Both the date of birth and the secondary ID number were exact matches with the data in the ID authority’s database

• Partial match: Either the date of birth OR the secondary ID number was an an exact match; the other was not a match

• No match: Both the date of birth and secondary ID number were no matches

We advise that you build your own business logic to handle cases where the overall result is a partial match. The business logic should be based on the individual match results of the date of birth and secondary ID number fields (returned as DOB and Secondary_ID_Number in the Actions object). The individual match results are based on the following:

Result Codes and Result Texts

General Failures Result Codes and Texts

This means no further processing is possible on the job. General failures occur when a job could not be submitted due to a logical/technical issue. These jobs do not show up in the portal and do not have a Smile Job ID.

Product Specific Result Codes and Texts