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 Enhanced KYC + SmartSelfie™ 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 Enhanced KYC + SmartSelfie™ 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. Perform an Authentication

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

Register a User

Make a Job Request

Request Type: POST

Keys

Type

Required

Description

file_name

string

Yes

This is the name of the zip file that will be uploaded in the PUT request to the upload URL

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

This is your partner id which can be found on the side navigation panel of the Smile ID partner portal

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

No

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

{
"file_name": "attachments.zip",
"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

not used if files are uploaded. for image list structure, read more on Smile ID image types

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

Full list of result codes below

ResultText

String

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

Full list of result text below.

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 selfie, it will be reviewed by humans. The result is displayed here

“Passed”

“Failed”

“Unable To Determine”

“Not Applicable”

Liveness_Check

String

Liveness check on user provided selfie

“Passed”

“Failed”

“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"

Example JSON Response

{
"Actions": {
"Human_Review_Compare": "Not Applicable",
"Human_Review_Liveness_Check": "Not Applicable",
"Human_Review_Update_Selfie": "Not Applicable",
"Liveness_Check": "Passed",
"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": "..."
}

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

Category

0001

Data Invalid

Rejected

0903

Zip Corrupt

Rejected

0907

FAIL - Possible Spoof - Strict Setting

Rejected

2405

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

-

2314

Error - No Zip File Received

-

2203

Error - Invalid JSON

-

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

-

2220

Error - Production is not enabled for this account. Please complete your KYC with Smile Identity.

-

2212

Error - Invalid job type **

-

2215

Error - Job already exists for job_id

-

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

Result Codes and Texts Specific to Registering a User

Code

Description

Result

0941

FAIL - No Face Found

Rejected

0942

FAIL - Image Quality Judged Too Poor

Rejected

0840

PASS - Machine Judgement

Approved

0841

FAIL - Machine Judgement - Compare Failed

Rejected

0842

PROVISIONAL - Machine - Pure Provisional

Provisionally Approved

0843

FAIL - Possible Spoof - Machine Judgement *

Rejected

0844

PROVISIONAL - Possible Spoof - Machine Judgement

Provisionally Approved

0846

PENDING - Possible Spoof - Machine Judgement

Pending

1240

PASS - Human Judgement

Approved

1241

FAIL - Image Unuseable

Rejected

1242

Spoof detected - Human Judgement

Rejected

Perform an Authentication

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

Keys

Type

Required

Description

file_name

string

Yes

This is the name of the zip file that will be uploaded in the PUT request to the upload URL

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

This is your partner id which can be found on the side navigation panel of the Smile ID partner portal

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

No

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

{
"file_name": "attachments.zip",
"sec_key": "<calculated sec_key>",
"timestamp": <timestamp used to calc sec_key parameter e.g. 1574065724378>,
"smile_client_id": "<partner id>",
"partner_params":
{
"job_type": "2"
"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

not used if files are uploaded. for image list structure, read more on Smile ID image types

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

Full list of result codes below

ResultText

String

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

Full list of result text below.

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 selfie, it will be reviewed by humans. The result is displayed here

“Passed”

“Failed”

“Unable To Determine”

“Not Applicable”

Liveness_Check

String

Liveness check on user provided selfie

“Passed”

“Failed”

“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”

Example JSON Response

{
"Actions": {
"Human_Review_Compare": "Not Applicable",
"Human_Review_Liveness_Check": "Passed",
"Human_Review_Update_Selfie": "Not Applicable",
"Liveness_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.000000",
"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",
"sec_key": "PZ5t29yjVPdO9v5a5fkzFrW9iUCBD2OuAmFLDVWX7yKWgwAXIoYG7VUJXOUJ8dMFQS1bBvubk+ERF7Ek4LChbkdCJEGErKE/SkK+Af8Kb3hVsBmWNDUx+o7U0wReWYkhwSXkvdxXMVHRZMgZb2puCkn2h5GOxDDzIimXk9APqfU=|196fb99a2608b2283953e2ee53c71ce0f5e75a114ccbc8ee581e273672f10052"
}

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

Category

0001

Data Invalid

Rejected

0903

Zip Corrupt

Rejected

0907

FAIL - Possible Spoof - Strict Setting

Rejected

2405

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

-

2314

Error - No Zip File Received

-

2203

Error - Invalid JSON

-

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

-

2220

Error - Production is not enabled for this account. Please complete your KYC with Smile Identity.

-

2212

Error - Invalid job type **

-

2215

Error - Job already exists for job_id

-

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

Product Specific Result Codes and Texts

Code

Text

Category

0921

FAIL - No Face Found

Rejected

0922

FAIL - Image Quality Judged Too Poor

Rejected

0820

Machine Judgement - PASS

Approved

0821

Machine Judgement - FAIL - COMPARISON

Rejected

0822

Machine Judgement - PURE PROVISIONAL

Provisionally Approved

0823

Machine Judgement - FAIL - Possible Spoof

Rejected

0824

Machine Judgement - PROVISIONAL - Possible Spoof

Provisionally Approved

0825

Machine Judgement - PROVISIONAL - Machine Compare Unsure

Provisionally Approved

1220

Human Judgement - PASS

Approved

1221

Human Judgement - FAIL - Human Compare Failed

Rejected

1222

Human Judgement - FAIL - Spoof Detected

Rejected

2208

Error - Enrolled user was deleted from the system

-

2207

Error - Enrolled user is disabled

-

2210

Error - No enrolled user found for user_id

-

2211

Error - Enrolled user must complete re-enrollment before attempting Auth

-