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.
Text
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.
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

Text	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> .

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

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

National ID (without Photo)

Test Data

Last modified 2mo ago

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.

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

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

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