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 , , and .

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

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

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

400: Bad Request

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

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

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

Info.json file

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)

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

How Smile ID Processes the Job

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

Actions Response

Example JSON Response

ID Information Response

Example JSON Response

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.

Product Specific Result Codes and Texts (Action Callback)

Product Specific Result Codes and Texts (ID Response Callback)

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.

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.