SmartSelfie™ Authentication

Overview

The SmartSelfie™ Authentication product lets you verify that an existing user is really the person attempting to access your system or service. SmartSelfie™ Authentication can be used as part of a multi-factor authentication system.

The SmartSelfie™ Authentication product is composed of two steps. The first step is to register a user and the second step is to authentic the previously registered user.

You can also perform a SmartSelfie™ Authentication for a user who has successfully performed an Biometric KYC or Document Verification.

Integration Options

Available on Mobile, Server-to-Server libraries and Rest API.

Registering a User

The SmartSelfie™ Authentication entails comparing a SmartSelfie™ against the Selfie on file of a registered user. To register a user, the job request payload is exactly the same as a SmartSelfie™ Authentication except for two differences (both changes are to be made in the Making a Job Request section of this page):

  1. Since you are just registering the user, you need a new user_id (details of Key in Making a Job Request section of this page)

  2. Set the job_type to 4 (details of Key in Making a Job Request section of this page)

If you are performing a SmartSelfie™ Authentication for a user you've previous Registered or performed ran a successful Biometric KYC or Document Verification on, you can skip the "Registering a User" section in the rest of this page.

Using the SmartSelfie™ Authentication Product

Follow the steps below to perform a SmartSelfie™ Authentication:

  1. Register a User

    1. Make a job request to register a user (ensure you take note of the user_id)

    2. Upload the job requirements

    3. Evaluate your result

  2. Perform an Authentication

    1. Make a job request to register a user (using the same user_id you used in registering your user)

    2. Upload the job requirements

    3. Evaluate your result

Register a User

Make a Job Request

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

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

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

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

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

just use the example below

images

in an image item all 3 parameters will exist: {

"image_type_id": 2,

"image": "<base64 string of image>",

"file_name": "<name of file in the zip that will be uploaded>"

}

Depending on the image_type_id one of the other parameters will be an empty string (“”)

Info.json Example

{
  "package_information":
  {
    "apiVersion": {
      "buildNumber": 0,
      "majorVersion": 2,
      "minorVersion": 0
    }
  },
  "images": [
    {
      <use either image or file_name, both cannot be used at the same time>
      "image_type_id": <0 | 2>,
      "image": "<base64 string of image>",
      "file_name": "<name of file in the zip that will be uploaded>"
    }
  ]
}

Return Values

You have submitted the job to Smile ID to register your user, the following keys are sent to your callback:

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.

4

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_Liveness_Check

String

If the Smile ID system can not automatically decide on the liveness of the user submitted liveness images, it will be 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 be 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”

Selfie_Provided

String

User provided a usable selfie

"Passed"

"Failed"

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

Example JSON Response

{
  "Actions": {
    "Human_Review_Compare": "Not Applicable",
    "Human_Review_Liveness_Check": "Not Applicable",
    "Human_Review_Update_Selfie": "Not Applicable",
    "Liveness_Check": "Passed",
    "Selfie_Check": "Passed",
    "Human_Review_Liveness_Check": "Not Applicable",
    "Register_Selfie": "Approved",
    "Return_Personal_Info": "Not Applicable",
    "Selfie_Provided": "Passed",
    "Selfie_To_ID_Authority_Compare": "Not Applicable",
    "Selfie_To_ID_Card_Compare": "Not Applicable",
    "Selfie_To_Registered_Selfie_Compare": "Not Applicable",
    "Update_Registered_Selfie_On_File": "Not Applicable",
    "Verify_ID_Number": "Not Applicable"
  },
  "ConfidenceValue": "99",
  "PartnerParams": {
    "job_id": "e9a81f6f-1de0-4226-a51b-71d56ffdd9ef",
    "job_type": 4,
    "user_id": "f77e03ec-6d1e-48d6-a4d1-38273dffe5b2"
  },
  "ResultCode": "0840",
  "ResultText": "Enroll User",
  "SmileJobID": "0000000027",
  "Source": "SDK - iPhone",
  "timestamp": "2021-08-12T17:57:00.614879",
  "signature": "----signature-----"
}

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.

How Smile ID Processes the Job

Action

Description

Proof of life & spoof detection

Performed on user submitted selfie

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.

Prefix for error codes may also be 23xx or 24xx

Code
Text
Description

2201

System Error

2203

Error - Invalid JSON

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

2204

Error - A parameter is of the wrong data type

2205

Error - You are not authorized to do that. *

2209

Error - User is already enrolled

The job was run with a duplicate user_id. Send the job with a unique user_id.

2212

Error - Invalid job type

An invalid value was inputted in the job_type key. Change the value to 4.

2213

Error - A required parameter is missing

2214

Error - Product not activated for this account

Product is deactivated on your account. Contact support to activate the product.

2217

Error - Invalid Product

2220

Error - Production is not enabled for this account.

2221

Error - Invalid token

Result Codes and Texts Specific to Registering a User

Code
Text
Description
Result

0001

Data Invalid

One of the required input is invalid.

0001

Data Invalid - Unable to extract zip file

There an an error encountered while attempting to extract the zip file. Confirm the images and info.json were archived properly and re-run the job.

0001

System Error

An unknown system error occurred while processing the job.

0840

Enroll User

PASS - Machine Judgement

Machine passed Selfie - no spoof detected and image contains a face.

Approved

0841

Failed Enroll

FAIL - Possible Spoof - Machine Judgement

Machine rejected job due to possible fraud attempt on the Selfie.

Rejected

0844

PROVISIONAL - Possible Spoof - Machine Judgement

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

0846 (deprecated)

PENDING - Possible Spoof - Machine Judgement

Awaiting document review result.

Pending

0941

FAIL - No Face Found

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

Rejected

0942

FAIL - Image Quality Judged Too Poor

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

Rejected

1240

Enroll User

PASS - Human Judgement

The human reviewer did not find any fraud attempts on the Selfie.

Approved

1241

Failed Enroll

FAIL - Image Unusable

The human reviewer marked the Selfie as unusable either because the Selfie is too dark or too blurry

Rejected

1242

Failed Enroll

Spoof detected - Human Judgement

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

Perform an Authentication

You must have performed either a a Document Verification, Biometric Registration or SmartSelfie™ Registration job before you can authenticate a user.

You have successfully registered a user and gotten the user_id of the user. Now you can perform an authentication against that user.

Make a Job Request

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

sec_key

string

Yes

Your calculated access signature

timestamp

string

Yes

The timestamp that was used to calculate the sec_key (in milliseconds)

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

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

The user ID of an existing user who has successfully been registered or gone through the Enhanced KYC + SmartSelfie™ or Document Verification products.

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://<partner side callback URL>/",
  "model_parameters": {},
  "partner_params": {
    "job_id": "job_09876",
    "job_type": 2,
    "user_id": "user_12345"
  },
  "signature": "<calculated signature>",
  "smile_client_id": "<partner id>",
  "source_sdk": "rest_api",
  "source_sdk_version": "1.0.0",
  "timestamp": "<timestamp used to calc signature>"
}

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

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

just use the example below

images

in an image item all 3 parameters will exist: {

"image_type_id": 2,

"image": "<base64 string of image>",

"file_name": "<name of file in the zip that will be uploaded>"

}

Depending in the image_type_id one of the other parameters will be an empty string (“”)

Info.json Example

{
  "package_information":
  {
    "apiVersion": {
      "buildNumber": 0,
      "majorVersion": 2,
      "minorVersion": 0
    }
  },
  "images": [
    {
      <use either image or file_name, both cannot be used at the same time>
      "image_type_id": <0 | 2>,
      "image": "<base64 string of image>",
      "file_name": "<name of file in the zip that will be uploaded>"
    }
  ]
}

Return Values

You have submitted the job to Smile ID to authenticate your user, the following keys are sent to your callback:

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.

2

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_Liveness_Check

String

If the Smile ID system can not automatically decide on the liveness of the user submitted liveness images, it will be 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 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 be reviewed by humans. The result is displayed here

“Passed”

“Failed”

“Unable To Determine”

“Under Review”

“Not Applicable”

Selfie_Provided

String

User provided a usable selfie

"Passed"

"Failed"

Selfie_To_Registered_Selfie_Compare

String

Compare user submitted selfie to user's Selfie on file

“Completed”

“Under Review”

“Not Applicable”

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

Example JSON Response

{
  "Actions": {
    "Human_Review_Compare": "Not Applicable",
    "Human_Review_Liveness_Check": "Passed",
    "Human_Review_Update_Selfie": "Not Applicable",
    "Liveness_Check": "Passed",
    "Selfie_Check": "Passed",
    "Human_Review_Selfie_Check": "Passed",
    "Register_Selfie": "Not Applicable",
    "Return_Personal_Info": "Not Applicable",
    "Selfie_Provided": "Passed",
    "Selfie_To_ID_Authority_Compare": "Not Applicable",
    "Selfie_To_ID_Card_Compare": "Not Applicable",
    "Selfie_To_Registered_Selfie_Compare": "Completed",
    "Update_Registered_Selfie_On_File": "Not Applicable",
    "Verify_ID_Number": "Not Applicable"
  },
  "ConfidenceValue": "99",
  "PartnerParams": {
    "job_id": "KE_TEST_1013",
    "job_type": 2,
    "user_id": "KE_TESTTEST_1012"
  },
  "ResultCode": "1220",
  "ResultText": "Authenticated",
  "SmileJobID": "0000057497",
  "Source": "WebAPI",
  "timestamp": "2021-06-21T15:10:15.729Z",
  "signature": "----signature-----"
}

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.

How Smile ID Processes the Job

Action

Description

Proof of life & spoof detection

Performed on user submitted selfie

Selfie compares

Selfie is compared to photo on User's photo on file in Smile ID

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.

Prefix for error codes may also be 23xx or 24xx

Code
Text
Description

2201

System Error

2203

Error - Invalid JSON

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

2204

Error - A parameter is of the wrong data type

2205

Error - You are not authorized to do that

2207

Error - Enrolled user is disabled

2208

Error - Enrolled user was deleted from the system

2210

Error - No enrolled user found

The user_id does not belong to an enrolled user. Confirm the user_id then re-run the authentication.

2211

Error - Enrolled user must complete re-enrollment

2212

Error - Invalid job type

An invalid value was inputted in the job_type key. Change the value to 2.

2213

Error - A required parameter is missing

2214

Error - Product not activated for this account

Product is deactivated on your account. Contact support to activate the product.

2215

Error - Job already exists for job_id

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

2216

Error - Enrolled user does not have a photo on file

2217

Error - Invalid Product

2220

Error - Production is not enabled for this account

2221

Error - Invalid token

Product Specific Result Codes and Texts

Code
Text
Description
Category

0001

Data Invalid

One of the required input is invalid.

0001

Data Invalid - Unable to extract zip file

There an an error encountered while attempting to extract the zip file. Confirm the images and info.json were archived properly and re-run the job.

0001

System Error

An unknown system error occurred while processing the job.

0820

Authenticate User

Machine Judgement - PASS

Comparison between the images matched.

Approved

0821

Failed Authentication

Machine Judgement - FAIL - COMPARISON

Images did not match and therefore job was rejected.

Rejected

0822

Machine Judgement - PURE PROVISIONAL

Waiting on document reviewer's decision.

Provisionally Approved

0823 (Deprecated)

Failed Authentication

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

0824

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.

Under Review

0825

Machine Judgement - PROVISIONAL - Machine Compare Unsure

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

Under Review

0921

FAIL - No Face Found

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

Rejected

0922

FAIL - Image Quality Judged Too Poor

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

Rejected

1220

Authenticate User

Human Judgement - PASS

The document reviewer marked that both images are of the same person.

Approved

1221

Failed Authentication

Human Judgement - FAIL - Human Compare Failed

The document reviewer marked that both images are different persons.

Rejected

1222

Failed Authentication

Human Judgement - FAIL - Spoof Detected

The document 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

PreviousPhone Number VerificationNextSmartSelfie™ Compare

Last updated