Basic KYC

Running Basic KYC in Uganda? Learn more here.

Overview

The Basic KYC API enables verification of an individual's identity information using their personal details and the ID number from one of our supported ID Types. This API returns a result of no match, partial match, or exact match, along with detailed data on the matching outcomes for specific fields.

Integration Options

Basic KYC is currently available only through 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 if the ID authority is unavailable. For high-volume applications, the Asynchronous API is required. If you are using the Asynchronous API, you must include a callback endpoint in your request to receive the response. 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

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

Environment

URL

Sandbox

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

Production

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

Request Values

The Basic KYC API requires the following input parameters in a JSON body object submitted to the endpoint:

Request Type: POST

source_sdk

string

Yes

The integration option you are using. For the REST API, send the value as "rest_api".

source_sdk_version

string

Yes

The version of the integration option you are using. This can be any value (including your own).

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. More information.

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

Middle name.

last_name

string

Yes

Last name.

dob

string

Date of birth (YYYY-MM-DD).

Note: For the Nigerian Voter ID, only the birth year should be entered in the format YYYY.

gender

string

Gender (M, F).

phone_number

string

Phone number.

partner_params

object

Yes

A JSON object containing the partner parameters listed 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 to 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 to 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": "Joe",
  "gender": "M",
  "id_number": "00000000000",
  "id_type": "NIN",
  "last_name": "Leo",
  "middle_name": "Doe",
  "partner_id": "023",
  "partner_params": {
    "job_id": "3ba0e15e-1a56-4799-a94d-b0e084f50256",
    "user_id": "4cb0f26-2b567-5800-b05e-c0f095g6036"
  },
  "phone_number": "0123456789",
  "signature": "...",
  "source_sdk_version": "2.0.0",
  "source_sdk": "rest_api",
  "timestamp": "2024-04-13T17:57:00.614879"
}

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.

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 the match outcome.

“Partial Match”, “Exact Match”, “No Match”

ResultCode

string

Numeric value of the match.

1020 = Exact Match, 1021 = Partial Match, 1022 = No Match. Find a list of potential error codes below.

IsFinalResult

string

Indicates if the response is final.

“True”

Actions

object

A JSON object containing the details of the individual field comparisons.

Return_Personal_Info

string

Confirms if the personal information retrieved from the ID authority was sent to you.

“Not Applicable”

Verify_ID_Number

string

The result of looking up the ID number in the ID authority database.

“Verified”, “Not Verified”, “Not Done”, “Issuer Unavailable”

Names

string

Result of comparing names supplied by the user with the names returned by the ID authority.

“Exact Match”, “Partial Match”, “Transposed”, “No Match”

DOB

string

Result of comparing the date of birth supplied by the user with 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 with the gender returned by the ID authority.

“Exact Match”, “No Match”, “Not Provided”

Phone_Number

string

Result of comparing the phone number supplied by the user with 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

The response you receive varies depending on whether you use the asynchronous or synchronous endpoint.

For the Asynchronous Endpoint:

{
  "success": true
}

For the Synchronous Endpoint (this response is also sent to the callback of the asynchronous endpoint):

{
  "JSONVersion": "1.0.0",
  "SmileJobID": "0000055474",
  "PartnerParams": {
    "job_id": "3ba0e15e-1a56-4799-a94d-b0e084f50256",
    "job_type": 5,
    "user_id": "4cb0f26-2b567-5800-b05e-c0f095g6036"
  },
  "ResultType": "ID Verification",
  "ResultText": "Exact Match",
  "ResultCode": "1020",
  "IsFinalResult": "true",
  "Actions": {
    "DOB": "Exact Match",
    "Gender": "Exact Match",
    "ID_Verification": "Exact Match",
    "Names": "Exact Match",
    "Phone_Number": "Exact Match",
    "Return_Personal_Info": "Not Applicable",
    "Verify_ID_Number": "Verified"
  },
  "Source": "ID Verification",
  "signature": "...",
  "timestamp": "2024-04-13T17: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

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. Basic KYC Result Codes fall into one of two categories:

Approved (or Pass) This means that all applicable Actions passed and the overall job was approved.
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

Code

Text

Description