Basic KYC
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.
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 |
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 | |
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 | |
id_type | string | Yes | |
id_number | string | Yes | |
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. |
{
"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"
}
}
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” |