ID Verification API v2

Overview

The ID verification 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.

Getting Started

Getting started is free and easy.

Core Libraries

In order to generate your security key, which is required to sign your requests to the Smile Identity APIs, we recommend using one of the following available libraries (Javascript, Java, Ruby, PHP or Python). If you do not find a Core Library for the language of your choice you can follow these instructions to calculate the key manually.

You will need to generate a security key and timestamp and pass them as parameters with each request. All responses will also contain the security key and timestamp allowing you to verify the authenticity of the response. At this point in time, the core libraries do not currently support submitting to the ID verification API directly and you will need to perform a standard HTTP post to the endpoints directly.

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 Identity Verification 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

sec_key

string

Yes

The outgoing signature to authenticate the request from you to Smile Identity

timestamp

string

Yes

The timestamp used to calculate the sec_key

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

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

{
"partner_id": "023",
"timestamp": 1556307484476,
"sec_key": "KeRTJu67ENWM8K/IFPxSxR1wswT4vkBFA+PY50OwOpGC1W4je/2FAVGTXl1whya4ZBz3OhH/uVhT0FM8ZuL/Xmc1m4bRus/oSQHvYHpu4R4tGQikUdRCHu5Vm/kCvLCbLX3Ds3vsvVrSpgL0znBCO2RjZgF3KfIsFr5c+kNheAY=|5c3e787bf807910e1b333d372ea57f85a28aa5a160ff60af562ed4815f503717",
"country": "NG",
"id_type": "DRIVERS_LICENSE",
"id_number": "ABC000000000",
"callback_url": "example.webhook.com"
"first_name": "Jane",
"middle_name": "Anne",
"last_name": "Doe",
"phone_number": "1234567890",
"dob": "1980-05-04",
"gender": "F",
"partner_params": {
"job_id": "3ba0e15e-1a56-4799-a94d-b0e084f50256",
"user_id": "4cb0f26-2b567-5800-b05e-c0f095g6036",
}
}

Return Values

The Identity verification 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

SmileJobID

string

The Smile internal reference number for the job

PartnerParams

object

The contents of the partner_params object from the request

ResultType

string

“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

For a list of potential error codes see here.

IsFinalResult

string

“True”

Actions

object

A JSON object containing the details of the individual field comparisons

Actions.Return_Personal_Info

string

“Not Applicable”

Actions.Verify_ID_Number

string

“Verified” || “Not Verified” || “Not Done” || “Issuer Unavailable”

Actions.Names

string

“Exact Match” || “Partial Match” || “Transposed” || “No Match”

Actions.DOB

string

“Exact Match” || “Partial Match” || “Transposed” || “No Match”

Actions.Gender

string

“Exact Match” || “No Match” || “Not Provided”

Actions.Phone_Number

string

“Exact Match” || “No Match” || “Not Provided”

Actions.ID_Verification

string

Same as ResultText

Example JSON Response

{
"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",
"sec_key": "iYzRQBsdJzJ/5/NrZOR9+aMKQ8ExvF8OdUv9okQy+ufTGsHJ/pErnSHE1lups4R0oSyjvJmCBwo/sqvYJaVM6XCq57RBTLuuulenv9K3UHQwX5O+Cve3vkMzwkQQvzXZl/Y2Sn/L0cK3kMgCjBD/ZDUm94puty0EGoohSaRwwJs=|c300ac3c6385708ab378253d2d9d6b2741d6c305edcf5305595d60db1498157e",
"timestamp": 1616762345173
}

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

Testing in Sandbox Mode

As you build your integration you can test against the sandbox endpoint using test data. You can run an unlimited number of requests against the sandbox endpoint using test data. If you attempt to use a real ID number against the sandbox endpoint you will receive an error. If you attempt to use test data against a production endpoint you will receive an error.

The sandbox endpoints for the ID verification API are:

Asynchronous:

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

Synchronous:

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

Moving to Production

Once you have completed testing and you are ready to move to production you just need to complete a few steps:

Asynchronous:

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

Synchronous:

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