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.

UgandaOther 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

EnvironmentURL

Sandbox

https://testapi.smileidentity.com/v2/verify_async

Production

https://api.smileidentity.com/v2/verify_async

Synchronous

EnvironmentURL

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.

Name

Type

Description

Return Values

SmileJobID

string

The Smile internal reference number for the job

PartnerParams

object

The contents of the partner_params object from the request

ResultType

string

The result type

“ID Verification”

ResultText

string

Textual value of match outcome

“Partial Match”

“Exact Match”

“No Match”

ResultCode

string

Numeric value of match

1020=Exact Match, 1021=Partial Match,

1022 = No Match

Find list of potential error codes below.

IsFinalResult

string

Is the response final

“True”

Actions

object

A JSON object containing the details of the individual field comparisons

{Return_Personal_Info

string

This key confirms if we sent the personal information retrieved from the ID authority sent to you

“Not Applicable”

Verify_ID_Number

string

The result of looking up the ID number in the ID authority database is returned in this key

“Verified”

“Not Verified”

“Not Done”

“Issuer Unavailable”

Secondary_ID_Number

string

Result of comparing secondary id number supplied by the user and the secondary id number returned by the ID authority

“Exact Match”

“No Match”

DOB

string

Result of comparing date of birth supplied by the user and the date of birth returned by the ID authority

“Exact Match”

“No Match”

Names

string

Result of comparing names supplied by the user and the names returned by the ID authority

Always "Not Provided" as name comparison is not supported

Gender

string

Result of comparing gender supplied by the user and the gender returned by the ID authority

Always "Not Provided" as gender comparison is not supported

Phone_Number

string

Result of comparing phone number supplied by the user and the phone number returned by the ID authority

Always "Not Provided" as phone number comparison is not supported

ID_Verification}

string

Same as ResultText

signature

string

The outgoing Signature, you can use this to verify that the response is from Smile ID

timestamp

string

The outgoing timestamp in ISO date/time format, use this to calculate the outgoing Signature

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)

{
    "JSONVersion": "1.0.0",
    "SmileJobID": "0000000571",
    "PartnerParams": {
        "job_id": "001",
        "user_id": "UG_Test_User_001",
        "job_type": 5
    },
    "ResultType": "ID Verification",
    "ResultText": "Exact Match",
    "ResultCode": "1020",
    "IsFinalResult": "true",
    "Actions": {
        "Return_Personal_Info": "Not Applicable",
        "Verify_ID_Number": "Verified",
        "Names": "Not Provided",
        "DOB": "Exact Match",
        "Gender": "Not Provided",
        "Phone_Number": "Not Provided",
        "Secondary_ID_Number": "Exact Match",
        "ID_Verification": "Exact Match"
    },
    "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:

Field

Exact Match

Partial Match

No Match

DOB

The date of birth shared matches exactly with what is in the ID authority database

Not Applicable

At least one digit varies in the date of birth or the month and day are transposed

Secondary_ID_Number

The card number shared matches exactly with what is in the ID authority database and there are no known issues with the document

Not Applicable

At least one digit varies in the card number that was shared or there are known issues with the document such as:

  • The document is expired

  • The document was reported stolen

  • The owner is deceased

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.

Code

Error

Description

0001

Data Invalid

2204

A parameter is of the wrong data type

The format of one of the request values was wrong. Please check request values for this product.

2205

You are not authorized to do that

An invalid signature was used to sign the request.

2220

Production is not enabled for this account. Please complete your KYC with Smile ID.​

You have not completed your KYC.

2212

Invalid job type

An invalid value was inputted in the job_type key. Change the value to "5".

2403

Invalid JSON

The request body is not properly formatted

2413

field_name is missing

A required key with the name field_name is missing

Product Specific Result Codes and Texts

Code

Text

Description

Category

1013

Invalid ID

The ID number was not found in the ID authority database.

Rejected

1014

Error - Unsupported ID number format

The ID number submitted was of an invalid format. Please enforce the Uganda National ID regex /^[A-Z0-9]{14}$/i

Rejected

1015

Error - Queried Database Unavailable

The ID authority is unavailable

Not Processed (Retry when the ID authority is back up)

1016

Error - Need to Activate Product

You do not have access to the ID Type. Please contact support for more information

Not Processed (Contact support to get access to the product)

1020

Exact Match

The submitted secondary ID number and date of birth exactly match the info in the ID authority database

Approved

1021

Partial Match

Only one of the secondary ID number or date of birth exactly matches the info in the ID authority database

Advised to process using internal business logic

1022

No Match

None of the secondary ID nor date of birth matched the info in the ID authority database

Rejected

Last updated