Enhanced KYC

NOTE

Only available to licensed organisations. Please contact [email protected] 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

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

partner_params.job_type

string

Yes

The type of job you want to perform. This will be set to 5.

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

partner_params.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",
    "job_type": 5,
    "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

Actions

object

A JSON object containing the details of the individual field comparisons

Actions.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"

Actions.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"

Address

string

Address of ID owner

NOTE: this might not be the current address of the ID owner

Country

string

Country where the ID was issued as supplied by you

CountryOfBirth

string

Country where the ID owner was born

DOB

string

Date of birth as retrieved from the ID authority database. It will be in the format "YYYY-MM-DD"

DateOfDeath

string

Date of death of the ID owner if isAlive is true

Document

string

Photo of ID card on file in the ID authority database (when applicable)

string

Email address of the ID owner if available

ExpirationDate

string

Expiration date as retrieved from the ID authority database

FirstName

string

First name of the ID owner

FullData

object

Deprecated This will be removed in the future

FullName

string

Full name as retrieved from the ID authority database. Typically a concatenation of all available names

Gender

string

Gender of ID owner

IDNumber

string

ID number you ran a query for

IDStatus

string

The status of the ID

IDType

string

ID type as supplied by you

ImageLinks

object

An object containing links to the id photo image if available. This is not returned when there is no image link.

ImageLinks.id_photo_image

string

Signed url to id photo image. This is not returned when there is no image link

IsAlive

string

If the ID owner is alive or not

IssuanceDate

string

Issuance date as retrieved from the ID authority database

LastName

string

Last name of the ID owner

LocalAreaOfOrigin

string

Local area of origin of the ID owner

Nationality

string

Nationality of the ID owner

OtherNames

string

Other names of the ID owner

PartnerParams

object

Object containing the parameters provided by you.

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

PartnerParams.user_id

string

A unique reference defined by you to keep track of the user

PhoneNumber

string

Top level key - phone number as retrieved from the ID authority database

PhoneNumber2

string

Second phone number of ID owner (when available)

Photo

string

Top level key - photo as retrieved from the ID authority database in base64 image

PlaceOfBirth

string

Place of birth within the country of birth of the ID owner

PlaceOfIssuance

string

Place of issuance within the country of issuance of the ID owner

RegionOfOrigin

string

Region of origin of the ID owner

ResultCode

string

Numeric value of the job outcome.

For a list of potential error codes see here.

ResultText

string

Textual value of the job outcome. Human readable value for the result.

Full list of result text in our documentation.

SecondaryIDNumber

string

Another ID number that is tied to another ID type

SmileJobID

string

The Smile internal reference number for the job. Please include this when contacting support on a job.

Source

string

The source of the initial request

Title

string

The title for addressing ID owner

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"
    },
    "Address": "",
    "Country": "NG",
    "CountryOfBirth": "",
    "DOB": "YYYY-MM-DD",
    "DateOfDeath": "",
    "Document": "",
    "Email": "",
    "ExpirationDate": "",
    "FirstName": "Joe",
    "FullData": {},
    "FullName": "Joe Leo Doe",
    "Gender": "M",
    "IDNumber": "00000000000",
    "IDStatus": "",
    "IDType": "NIN_V2",
    "ImageLinks": {
        "id_photo_image": "https://signed-url"
    },
    "IsAlive": "",
    "IssuanceDate": "",
    "LastName": "Leo",
    "LocalAreaOfOrigin": "",
    "Nationality": "",
    "Occupation": "",
    "OtherNames": "Leo",
    "PartnerParams": {
        "job_id": "job_687785e05ead41.22504990",
        "job_type": 5,
        "user_id": "user_687785e05eada7.97747137"
    },
    "PhoneNumber": "0123456789",
    "PhoneNumber2": "",
    "Photo": "",
    "PlaceOfBirth": "",
    "PlaceOfIssuance": "",
    "RegionOfOrigin": "",
    "ResultCode": "1012",
    "ResultText": "ID Number Validated",
    "SecondaryIDNumber": "AAAAAA-0000",
    "SmileJobID": "0000123456",
    "Source": "Async ID API",
    "Title": "",
    "signature": "==signature returned==",
    "timestamp": "==timestamp returned=="
}

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:

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

Product Specific Result Codes and Texts

Code

Text

Description