Biometric KYC

Overview

The Biometric KYC product lets you verify the ID information of your user and confirm that the ID actually belongs to the user, this is achieved by comparing the user's SmartSelfie™ (a combination of liveness images and a primary image) to the photo of the user on file in an ID authority database.

Integration Options

Available via the Rest API, Mobile, Server to Server and Web SDK.

Request Values

You need to perform two steps to use this product:

  • Make a request to Smile ID for a job to be performed

  • Upload the requirements for the job

Making a Job Request - Prep Upload

Request Type: POST

Environment
URL

Sandbox

Production

Keys

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

signature

string

Yes

Your calculated access signature

timestamp

string

Yes

The timestamp that was used to calculate the sec_key (in ISO date/time format)

smile_client_id

string

Yes

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

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.

model_parameters

string

No

This parameter is specific to mobile SDK, can be left as an empty JSON object

callback_url

string

Yes

An endpoint on the partner side where Smile ID will send the results of a job to in the form of a POST request (with no authorisation headers)

At the end of the request, you will receive a job number for tracking and a url where you will be uploading your images

Example Request

{
  "callback_url": "https://<your callback URL>/",
  "model_parameters": {},
  "partner_params": {
    "job_id": "job_09876",
    "job_type": 1,
    "user_id": "user_12345"
  },
  "signature": "<calculated signature>",
  "smile_client_id": "<partner id>",
  "source_sdk_version": "1.0.0",
  "source_sdk": "rest_api",
  "timestamp": "<timestamp e.g. 2021-08-12T17:57:00.614879>"
}

In the response body to the prep upload request, you will receive an AWS s3 bucket link. You will upload the images for face verification to this link. The URL is structured like:

"https://smile-uploads-test.s3.us-west-2.amazonaws.com/videos/ <partner_id>/<partner_id>-<smile_job_id>-<random hash>/attachments.zip ?AWSAccessKeyId=<> &Content-Type=application%2Fzip &Expires=1598449184&Signature=<> &x-amz-security-token=<>&x-amz-server-side-encryption=AES256"

Example Response

200: OK

A record has now been created waiting for the job to be processed once the required data has been uploaded

{
    "upload_url": "https://smile-uploads-test.s3.us-west-2.amazonaws.com/videos/<partner_id>/<partner_id>-<smile_job_id>-<random hash>/selfie.zip?AWSAccessKeyId=<>&Content-Type=application%2Fzip&Expires=1598449184&Signature=<>&x-amz-security-token=<>&x-amz-server-side-encryption=AES256",
    "ref_id": "<partner_id>-<smile_job_id>-<random hash>",
    "smile_job_id": "0000000001",
    "camera_config": "null", ---sdk specific---
    "code": "2202"
}

400: Bad Request

Trying to use a job_id in partner_params that has already been used

{
  "error": "Job already exists. Did you mean to set the retry flag to true?",
  "code": "2215"
}

Uploading the Job Requirements

To perform a job, Smile ID requires a Zip file that contains the following information:

  • images - images are Selfie and/or ID card photo and/or liveness images

  • Info.json file - the structure of the info.json file is detailed below

The images can either be parsed inline as a base64 encoded string or the image files themselves can be zipped with the info.json file. Only .jpg file type is supported.

Request Type: PUT

Environment
URL

Sandbox

Upload URL you were supplied while making a Job Request

Production

Upload URL you were supplied while making a Job Request

The request body will be of type binary (the zip file)

Info.json file

Parameter
Description

package_information

This contains information about the rest api you’re calling. We recommend you use the following as the package_information:

"package_information":

{

"apiVersion": {

"buildNumber": 0,

"majorVersion": 2,

"minorVersion": 0

}

}

id_info

"id_info":

{

"country":"<country code e.g. KE>",

"id_type":"<smile ID type keyword e.g. NATIONAL_ID>"

}

images

The images required for the document verification job. There are 2 image types that can be uploaded:

  • Selfie - one RGB (colour) selfie image of the user

  • Liveness images (optional) - 8 colour images of the user’s face captured while the user was prepping to take the selfie image (it’s recommended you use either our mobile SDKs or Javascript SDK to capture the liveness images)

The images can be added as base64 encoded strings or the image files themselves can be added to the zip and the filename specified in the info.json.

{

"image": "",

"file_name": "" }

Depending on the image_type_id one of the other parameters (image or file_name) will be an empty string i.e. “”

Info.json Example

As explained the zip file contains the info.json file only (if images are inline i.e. supplied as base64 encoded strings) or both an info.json file and image files (if the image files themselves are uploaded).

Example zip file and info.json when Images are Inline (i.e. Base64 Encoded Strings)

Note: "entered":true in ID info is required.

{
  "package_information":
  {
    "apiVersion": {
      "buildNumber": 0,
      "majorVersion": 2,
      "minorVersion": 0
    }
  },
  "id_info":
  {
    "dob":"<dob in ID type specific format>",
    "country":"<country code e.g. KE>",
    "entered":true <job type 1> | false,
    "id_type":"smile ID type keyword e.g. NATIONAL_ID",
    "id_number":"The ID number e.g. 00000000",
    "last_name":"Joe",
    "first_name":"Leo",
    "middle_name":"Doe"
  },
  "images": [
    {
      <Selfie image>
      "image_type_id": 2,
      "image": "VBORw0KGgoAAAANSUhEUgAAArg---truncated base64 string",
      "file_name": ""
    },
    {
      <liveness images, repeat this json blob for all 8 colour images>
      "image_type_id": 6,
      "image": "iVBORw0KGgoAAAANSUhEUgAAAjoAAAFaCAYA---truncated base64 string",
      "file_name": ""
    }
  ]
}

Example zip file and info.json when Images are uploaded as files

{
  "package_information":
  {
    "apiVersion": {
      "buildNumber": 0,
      "majorVersion": 2,
      "minorVersion": 0
    }
  },
  "id_info":
  {
    "dob":" <dob in ID type specific format>",
    "country":" <country code e.g. KE>",
    "entered":true <job type 1> | false,
    "id_type":"smile ID type keyword e.g. NATIONAL_ID",
    "id_number":"The ID number e.g. 00000000",
    "last_name":"Joe",
    "first_name":"Leo",
    "middle_name":"Doe"
  },
  "images": [
    {
      <Selfie image>
      "image_type_id": 0,
      "image": "",
      "file_name": "Selfie.jpeg"
    },
  {
      <liveness images, repeat this json blob for the other 8 colour images>
      "image_type_id": 4,
      "image": "",
      "file_name": "1.jpg"
    }
  ]
}

How Smile ID Processes the Job

Action

Description

ID lookup in ID authority database

ID information is queried in ID authority database

Proof of life & spoof detection

Performed on user submitted selfie

Selfie compares

If photo is available in ID authority database, Selfie is compared to photo on file else Selfie is compared to user submitted ID card photo

Return Values

For each successful Biometric KYC job, you will get two different responses to your callback:

  1. Actions response which details the actions that were carried out on the job

  2. ID information response which contains the information of the user retrieved from the ID authority

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.

Actions Response

Name

Type

Description

Return Values

ConfidenceValue

String

Smile ID’s confidence that the user should be registered. Values are between 0% - 100%

0% - 100%

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.

1

PartnerParams.user_id

String

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

ResultCode

String

Numeric value of the job outcome.

ResultText

String

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

SmileJobID

String

The Smile internal reference number for the job

Actions

Object

The JSON object contains the results of checks Smile ID performed on the job

{Human_Review_Compare

String

If the Smile ID system can not automatically decide on the face compares it will be reviewed by humans and the result will be displayed here

“Passed”

“Failed”

“Unable to Determine”

“Not Applicable”

Human_Review_Liveness_Check

String

If the Smile ID system can not automatically decide on the liveness of the user submitted liveness images, it will reviewed by humans. The result is displayed here

“Passed”

“Failed”

“Unable To Determine”

“Under Review”

“Not Applicable”

Liveness_Check*

String

Liveness check on user provided liveness images.

“Passed”

“Failed”

“Under Review”

“Not Applicable”

Selfie_Check

String

Passive liveness check on the user provided selfie

“Passed”

“Failed”

“Under Review”

“Not Applicable”

Human_Review_Selfie_Check

String

If the Smile ID system can not automatically decide on the checks of the user submitted selfie, it will reviewed by humans. The result is displayed here

“Passed”

“Failed”

“Unable To Determine”

“Under Review”

“Not Applicable”

Register_Selfie

String

Register selfie of user

“Approved”

“Rejected”

“Provisionally Approved”

“Not Applicable”

Return_Personal_Info

String

Return user’s PII from ID authority

“Returned”

“Not Returned”

“Not Applicable”

Selfie_Provided

String

User provided a usable selfie

Selfie_To_ID_Authority_Compare

String

Compare user submitted selfie to government ID authority photo

“Completed”

“Under Review”

“ID Authority Photo Not Available”

“Not Applicable”

Selfie_To_ID_Card_Compare

String

Compare user submitted to user submitted ID card photo

“Completed”

“Under Review”

“Not Applicable”

Verify_ID_Number

String

Query ID number in the ID authority database

“Verified”

“Not Verified”

“Issuer Unavailable”

“Not Applicable”

* If a single selfie image is provided, the system will only perform a Selfie_Check

Example JSON Response

{
  "Actions": {
    "Human_Review_Compare": "Passed",
    "Human_Review_Liveness_Check": "Passed",
    "Human_Review_Selfie_Check": "Passed",
    "Human_Review_Update_Selfie": "Not Applicable",
    "Liveness_Check": "Passed",
    "Register_Selfie": "Approved",
    "Return_Personal_Info": "Returned",
    "Selfie_Check": "Passed",
    "Selfie_Provided": "Passed",
    "Selfie_To_ID_Authority_Compare": "Completed",
    "Selfie_To_ID_Card_Compare": "Not Applicable",
    "Selfie_To_Registered_Selfie_Compare": "Not Applicable",
    "Update_Registered_Selfie_On_File": "Not Applicable",
    "Verify_ID_Number": "Verified"
  },
  "ConfidenceValue": "99",
  "PartnerParams": {
    "job_id": "KE_TEST_100",
    "job_type": 1,
    "user_id": "KE_TESTTEST_100"
  },
  "ResultCode": "1210",
  "ResultText": "Enroll User",
  "SmileJobID": "0000056574",
  "Source": "WebAPI",
  "timestamp": "2021-05-06T08:48:50.763Z",
  "signature": "----signature-----"
}

ID Information Response

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

1

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.

ResultCode

string

Numeric value of the job outcome.

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"

Return_Personal_Info

string

This key confirms if we sent the personal information retrieved from the ID authority sent to you

"Returned" "Not Returned"

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

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

IDNumberPreviouslyRegistered

boolean

Boolean value that informs you if ID info has previously been used successfully to register a user.

Only available on Biometric KYC product.

true or false

UserIDsOfPreviousRegistrants

array

Registered User IDs that have previously used the ID info you just queried.

Only available on Enhanced KYC + SmartSelfie™ product.

["12134","23456"]

KYCReceipt

string

Example JSON Response

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

Evaluating the Results

Actions performed on the product are not completed at the same time, so we send results to your callback as they are ready. Also, if the Smile ID system can not automatically make a decision on an action it is passed to human reviewers, the system decision is sent via callback pending the time the reviewers make a final decision.

You can get the results of the job anytime by using the Job Status endpoint. Read more about the Job Status endpoint in the Utilities section of any integration option of your choice.

Result Codes and Result Texts

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

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

  2. Provisionally Approved This means that the job is awaiting a human review, or that a human review was inconclusive or that part of a job passed but another part was unable to be completed. You can treat these jobs as Approved or you handle them based on the Result Code. Please note a Pure Provisional result is a provisionally approved job, but one in which the image comparison Action was provisionally approved but the identity validation Action failed or could not return data. Also note, a Pending Approval result is a custom Strict setting where the user cannot progress in the system without a human review being completed on the Pending job.

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

Uploaded zip is corrupted

Rejected

0001

ID Authority image not available

There was no photo returned by the id authority for the submitted ID number

Rejected

0001

ID Card image unusable

The submitted ID card image is corrupted or was not included in zip

Rejected

0903

Zip Corrupt

The uploaded Zip file is corrupted.

Rejected

0907 (deprecated)

FAIL - Possible Spoof - Strict Setting

The machine detected a possible spoof and product was ran as strict.

Rejected

2405

Error - "You are not authorized to do that" *

An invalid signature was used to sign the request.

-

2314

Error - No Zip File Received

No Zip files was uploaded.

-

2203

Error - Invalid JSON

The info.json file in the Zip is not properly structured. Ensure all keys are present and properly named.

-

2213

Error - A required parameter is missing

-

2204

Error - A parameter is of the wrong data type

-

2205

Error - You are not authorized to do that. *

An invalid signature was used to sign the request.

-

2220

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

-

2215

Error - Job already exists for job_id

An existing job_id was inputted. Enter a unique job id.

-

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

Product Specific Result Codes and Texts (Action Callback)

Code
Text
Description
Category

1013

Invalid ID

The ID info provided was not found in the ID authority database.

Rejected

1014

Unsupported ID number format

Rejected

1015

Error - Queried Database Unavailable

The ID authority is unavailable.

Re-run the job when ID authority is back online

0911

No Face Found

There was no face found in the uploaded selfie. Upload an image with a face.

Rejected

0912

Image Quality Judged Too Poor

The uploaded selfie quality was too poor. Upload a higher quality selfie.

Rejected

0810

Enroll User

Machine Judgement - PASS

Images matched and no spoof detected on the selfie.

Approved

0811

Failed Enroll

Machine Judgement - FAIL - Compare Rejected

Images did not match and job was therefore rejected.

Rejected

0812

Machine Judgement - Pure Provisional

Waiting on document reviewer's decision.

Provisionally Approved

0813

Failed Enroll

Machine Judgement - FAIL, Possible Spoof

Machine rejected job due to possible fraud attempt on the Selfie - This can be fraud attempt or some times images are too blurry or dark in the liveness check to make a decision.

Rejected

0814

Machine Judgement - Provisional - Possible Spoof

The machine thinks there is a possible spoof but can't make a final decision. A document reviewer will check the Selfie for potential fraud attempts.

Suspected for spoof and sent to document reviewer for final decision

0815

Machine Judgement - Provisional - Compare Unsure

The machine is not sure if both images match, so a document reviewer will compare.

Provisionally Approved

1210

Enroll User

Human Judgement - PASS

The human reviewer marked that both images are of the same person and no spoof was detected.

Approved

1211

Failed Enroll

Human Judgement - FAIL - Human Compare Failed

The human reviewer marked that both images are different persons.

Rejected

1212

Failed Enroll

Human Judgement - Spoof Detected

The human reviewer detected a possible fraud attempt on the Selfie - This can be a fraud attempt or some times images are too blurry or dark in the liveness check to make a decision.

Rejected

1213

Human Judgement - Provisional - Liveliness Unsure

The human reviewer is not sure if there is a possible fraud attempt on the Selfie.

Inconclusive

0908

Error - Issuer not available

The ID authority is unavailable.

Re-run the job when ID authority is back online

1016

Error - Need to Activate Product

You do not have access to the ID Type. Please contact support for more information.

2209

Error - This user is already enrolled with user_id

An existing user_id was inputted. Enter a unique user id.

Re-run the job with a different user_id

Product Specific Result Codes and Texts (ID Response Callback)

Code
Description
Category

1012

ID Verification Success

The ID info is valid and was found in the ID authority database.

ID info is valid

1013

Invalid ID

The ID info was not found in the ID authority database.

Rejected

1014

Unsupported ID number format

Rejected

1015

Error - Queried Database Unavailable *

The ID authority is unavailable.

Re-run the job when ID authority is back online

Spotting Repeat ID Number Usage

We recognise that there are legitimate reasons why a user may need multiple accounts using the same credentials for KYC. As a result, we allow your users to register a selfie with an ID Number multiple times.

However, we track if an ID has previously been used to run a successful Biometric KYC and return the user_ids of all those users. There are two methods to get the list of user_id(s) who have previously used the ID:

ID Response sent to your Callback

If the ID number submitted with the job has been previously used, we return true in the IDNumberPreviouslyRegistered key and all registered user_ids are listed in the array UserIDsOfPreviousRegistrants as shown above. Both the IDNumberPreviouslyRegistered and UserIDsOfPreviousRegistrants are keys in the ID response sent to the callback you specified when running the job.

Polling Job Status

If the ID number submitted with the job has been previously used, we return true in the IDNumberPreviouslyRegistered key and all registered user_ids are listed in the array UserIDsOfPreviousRegistrants as shown above. Both the IDNumberPreviouslyRegistered and UserIDsOfPreviousRegistrants are sub-keys in the history object of the job status response.

PreviousBasic KYCNextDocument Verification

Last updated