Basic KYC

Running Basic KYC in Uganda? Read more about it here.
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.
Integration Options
Currently only available via the Rest API.
Asynchronous vs Synchronous
This API is available as both an Asynchronous API (recommended) which guarantees an eventual response regardless of ID authority availability and as a Synchronous API to be used in real time environments such as mobile applications which does not guarantee a response in the case 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 which 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
Country code. Link to country codes here​
id_type
string
Yes
​Supported ID type​
id_number
string
Yes
ID number, you can enforce ID number format using our regex examples here

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​
first_name
string
Yes
First Name
middle_name
string
No
Middle Name
last_name
string
Yes
Last Name
dob
string
No
Date of Birth (YYYY-MM-DD)
gender
string
No
Gender (M, F)
phone_number
string
No
Phone Number
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": "NG",
    "id_type": "NIN",
    "id_number": "00000000000",
    "callback_url": "example.webhook.com",
    "first_name": "Joe",
    "middle_name": "Doe",
    "last_name": "Leo",
    "phone_number": "0123456789",
    "dob": "2000-09-20",
    "gender": "M",
    "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 as well as 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”
Names
string
Result of comparing names supplied by the user and the names returned by the ID authority
“Exact Match”
“Partial Match”
“Transposed”
“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”
“Partial Match”
“Transposed”
“No Match”
Gender
string
Result of comparing gender supplied by the user and the gender returned by the ID authority
“Exact Match”
“No Match”
“Not Provided”
Phone_Number
string
Result of comparing phone number supplied by the user and the phone number returned by the ID authority
“Exact Match”
“No Match”
“Not Provided”
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": "0000055474",
    "PartnerParams": {
        "user_id": "4cb0f26-2b567-5800-b05e-c0f095g6036",
        "job_id": "3ba0e15e-1a56-4799-a94d-b0e084f50256",
        "job_type": 5
    },
    "ResultType": "ID Verification",
    "ResultText": "Exact Match",
    "ResultCode": "1020",
    "IsFinalResult": "true",
    "Actions": {
        "Return_Personal_Info": "Not Applicable",
        "Verify_ID_Number": "Verified",
        "Names": "Exact Match",
        "DOB": "Exact Match",
        "Gender": "Exact Match",
        "Phone_Number": "Exact Match",
        "ID_Verification": "Exact Match"
    },
    "Source": "ID Verificaiton",
    "signature": "...",
    "timestamp": "2021-08-12T17:57:00.614879"
}
Evaluating the Results
You can choose to use the ResultCode and ResultText to make a verification decision or you can make a more granular decision based on the values from the individual fields located in the actions object. If all the underlying fields are an exact match the overall result is an exact match. If all the underlying fields are any mixture of exact, partial match, or transposed then the overall result is a partial match. If any of the fields are no match then the entire result is no match. Here is an explanation of the matching rules:
Exact Match
The values are a case-insensitive exact match
Partial Match
For name values it is a partial match if the values are a levenshtein distance of <= 2 apart. For date of birth it is a partial match if any single component (Day, Month, Year) is within 1 digit of the returned value. If more than one component of date birth is off then it is no match.
Transposed
Two elements are transposed. For example first name and last name or month of birth and date of birth
Not Provided
An optional field was not provided with the request
No Match
All other cases
Result Codes and Result Texts
Result codes details what the current (or final) result of a job is. Result Codes for all jobs fall into one of three categories:
1.Approved (or Pass)
This means that all applicable Actions passed and the overall job was approved.
2.Provisionally Approved
This means that the job is awaiting a human review, or that a human review was inconclusive or that part of a job passed but another part was unable to be completed.
You can treat these jobs as Approved or you handle them based on the Result Code.
Please note a Pure Provisional result is a provisionally approved job, but one in which the image comparison Action was provisionally approved but the identity validation Action failed or could not return data. Also note, a Pending Approval result is a custom Strict setting where the user cannot progress in the system without a human review being completed on the Pending job.
3.Rejected (or Fail)
This means that one or more of the applicable Actions for job failed, and thus, the overall job was rejected according to Smile ID standards.
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
Text
Description
Category
0001
Data Invalid
​
Rejected
2405
Error - "You are not authorized to do that" *
An invalid signature was used to sign the request.
-
2213
Error - A required parameter is missing
Not all the required keys were submitted in the info.json or request payload. Please check request values for this product.
-
2204
Error - 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
Error - You are not authorized to do that. *
An invalid signature was used to sign the request.
-
2220
Error - Production is not enabled for this account. Please complete your KYC with Smile ID.​
You have not completed your KYC.
-
2212
Error - Invalid job type **
An invalid value was inputted in the job_type key. Change the value to "5".
-
2413
Error - valid id_type is required
An invalid or unsupported country/id_type pair was used in the request
-
* - read more on how to troubleshoot this error here
** - set Job Type to "5"
Product Specific Result Codes and Texts
Code
Text
Description
Category
1013
Invalid ID
The ID info 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 use our regex samples as a guide.
-
1015
Error - Queried Database Unavailable
The ID authority is unavailable.
-
1016
Error - Need to Activate Product
You do not have access to the ID Type. Please contact support for more information.
-
1020
Exact Match
The user submitted details exactly match the ID info in the ID authority database.
Approved
1021
Partial Match
At least one of the user submitted details partially/exactly match the ID info in the ID authority database.
Approved
1022
No Match
None of the user submitted details partially/exactly match the ID info in the ID authority database.
Rejected

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

Exact Match	The values are a case-insensitive exact match
Partial Match	For name values it is a partial match if the values are a levenshtein distance of <= 2 apart. For date of birth it is a partial match if any single component (Day, Month, Year) is within 1 digit of the returned value. If more than one component of date birth is off then it is no match.
Transposed	Two elements are transposed. For example first name and last name or month of birth and date of birth
Not Provided	An optional field was not provided with the request
No Match	All other cases

Code	Text	Description	Category
0001	Data Invalid		Rejected
2405	Error - "You are not authorized to do that" *	An invalid signature was used to sign the request.	-
2213	Error - A required parameter is missing	Not all the required keys were submitted in the info.json or request payload. Please check request values for this product.	-
2204	Error - 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	Error - You are not authorized to do that. *	An invalid signature was used to sign the request.	-
2220	Error - Production is not enabled for this account. Please complete your KYC with Smile ID.	You have not completed your KYC.	-
2212	Error - Invalid job type **	An invalid value was inputted in the job_type key. Change the value to "5".	-
2413	Error - valid id_type is required	An invalid or unsupported country/id_type pair was used in the request	-

Code	Text	Description	Category
1013	Invalid ID	The ID info 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 use our regex samples as a guide.	-
1015	Error - Queried Database Unavailable	The ID authority is unavailable.	-
1016	Error - Need to Activate Product	You do not have access to the ID Type. Please contact support for more information.	-
1020	Exact Match	The user submitted details exactly match the ID info in the ID authority database.	Approved
1021	Partial Match	At least one of the user submitted details partially/exactly match the ID info in the ID authority database.	Approved
1022	No Match	None of the user submitted details partially/exactly match the ID info in the ID authority database.	Rejected

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	Country code. Link to country codes here
id_type	string	Yes	Supported ID type
id_number	string	Yes	ID number, you can enforce ID number format using our regex examples here
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
first_name	string	Yes	First Name
middle_name	string	No	Middle Name
last_name	string	Yes	Last Name
dob	string	No	Date of Birth (YYYY-MM-DD)
gender	string	No	Gender (M, F)
phone_number	string	No	Phone Number
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.