Enhanced KYC

NOTE

Only available to licensed organisations. Please contact [e-mail] if you need access to this product.

Overview

The Enhanced KYC API allows you to query the Identity Information for an individual using their ID number from one of our supported ID Types. This API will return the personal information of the individual found in the database of the ID authority.

Integration Options

Only available using Mobile, Server-to-Server and Rest APIs.

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:

The size of the payload sent to your callback varies based on the size of image returned by the ID authority. We recommend your callback should accept payloads up to 1.5MB in size.

Asynchronous:

Environment	URL
Sandbox:	https://testapi.smileidentity.com/v1/async_id_verification
Production:	https://api.smileidentity.com/v1/async_id_verification

Synchronous:

Environment	URL
Sandbox:	https://testapi.smileidentity.com/v1/id_verification
Production:	https://api.smileidentity.com/v1/id_verification

Request Values

The Enhanced 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
partner_id	string	Yes	A unique number assigned by Smile ID to your account. Can be found with your API key here
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
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	The country where the ID was issued. Link to country codes here
id_type	string	Yes	The type of ID you want to look up. Supported ID type
id_number	string	Yes	ID number, you can enforce ID number format using our regex examples here
callback_url	string	Yes for 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	Varies by ID Type	First Name
middle_name	string	No	Middle Name
last_name	string	Varies by ID Type	Last Name
dob	string	Varies by ID Type	Date of Birth
phone_number	string	Varies by ID Type	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_type	string	Yes	The type of job you want to perform. This will be set to 5.
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

{
  "callback_url": "example.webhook.com",
  "country": "NG",
  "dob": "2000-09-20",
  "first_name": "Leo",
  "gender": "M",
  "id_number": "ABC000000000",
  "id_type": "DRIVERS_LICENSE",
  "last_name": "Joe",
  "middle_name": "Doe",
  "partner_id": "023",
  "partner_params": {
    "job_id": "3ba0e15e-1a56-4799-a94d-b0e084f50256",
    "user_id": "4cb0f26-2b567-5800-b05e-c0f095g6036"
  },
  "phone_number": "1234567890",
  "signature": "...",
  "source_sdk": "rest_api",
  "source_sdk_version": "1.0.0",
  "timestamp": "2021-08-12T17:57:00.614879"
}

Return Values

The Enhanced 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. Please include this when contacting support on a job.
PartnerParams.job_id	String	A unique reference defined by you to keep track of the job
PartnerParams.job_type	String	The type of job you performed	5
PartnerParams.user_id	String	A unique reference defined by you to keep track of the user
ResultText	string	Textual value of the job outcome. Human readable value for the result.	Full list of result text in our documentation.
ResultCode	string	Numeric value of the job outcome.	For a list of potential error codes see here.
Actions	object	A JSON object containing the details of the individual field comparisons
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"
Return_Personal_Info	string	This key confirms if we sent the personal information retrieved from the ID authority sent to you	"Returned" "Not Returned" "Not Applicable"
Country	string	Country where the ID was issued as supplied by you
IDType	string	ID type as supplied by you
IDNumber	string	ID number you ran a query for
IssuanceDate	string	Top level key - issuance date as retrieved from the ID authority database
ExpirationDate	string	Top level key - expiration date as retrieved from the ID authority database
FullName	string	Top level key - full name as retrieved from the ID authority database
DOB	string	Top level key - date of birth as retrieved from the ID authority database
PhoneNumber	string	Top level key - phone number as retrieved from the ID authority database
PhoneNumber2	string	Second phone number of ID owner (when available)
Document	string	Photo of ID card on file in the ID authority database (when applicable)
Gender	string	Gender of ID owner
Address	string	Address of ID owner NOTE: this might not be the current address of the ID owner
SecondaryIDNumber	string	Another ID number that is tied to another ID type
Photo	string	Top level key - photo as retrieved from the ID authority database in base64 image
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)

{
  "Actions": {
    "Return_Personal_Info": "Returned",
    "Verify_ID_Number": "Verified"
  },
  "Country": "NG",
  "DOB": "2000-09-20",
  "ExpirationDate": "2021-08-15",
  "IssuanceDate": "2000-01-01",
  "FullName": "Leo Doe Joe",
  "IDNumber": "ABC000000000",
  "SecondaryIDNumber": "000000000",
  "IDType": "DRIVERS_LICENSE",
  "PartnerParams": {
    "job_id": "FS1kd1dd15JUpd87gTBDapvFxv0",
    "job_type": 5,
    "user_id": "T6yzdOezucdsPrY0QG9LYNDGOrC"
  },
  "Photo": "<BASE64 STRING>",
  "ResultCode": "1012",
  "ResultText": "ID Number Validated",
  "SmileJobID": "0000000001",
  "signature": "...",
  "timestamp": "2021-08-12T17:57:00.614879"
}

Evaluating the Results

The Enhanced KYC product returns the personal information of users stored in the ID authority database. Each ID authority stores these personal information with different keys causing discrepancies in names of keys containing similar information. For the identity lookup response, we have filtered and standardised the personal information returned to top-level keys to simplify the use of our JSON response across all our supported ID types.

Result Codes and Result Texts

Result codes details what the current (or final) result of a job is. Result Codes for all Enhanced KYC jobs fall into one of two categories:

1. Approved (or Pass) This means that all applicable Actions passed and the overall job was approved.

2. 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
2405	Error - "You are not authorized to do that" *	An invalid signature was used to sign the request.	-
2203	Error - Invalid JSON	The json request body is not properly structured. Ensure all keys are present and properly named and in lower case.	-
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.	-

* - read more on how to troubleshoot this error here ** - set Job Type to 5

Product Specific Result Codes and Texts

Code	Text	Description	Category
1012	Valid ID		Approved
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.	-
2211	(Mobile SDK Only) ID Validation Failed		Rejected
2212	(Mobile SDK Only) Error - HTTP Request Failed		-