Ask or search…
K

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. 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. 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. 1.
    Register a User
    1. 1.
      Make a job request to register a user (ensure you take note of the user_id)
  2. 2.
    Perform an Authentication
    1. 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
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
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
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
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 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.
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 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. 1.
    Approved (or Pass) This means that all applicable Actions passed and the overall job was approved.
  2. 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. 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
The format of one of the request values was wrong. Please check request values for this product.
2205
Error - You are not authorized to do that. *
An invalid signature was used to sign the request. Read more on how to troubleshoot this error here.
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
Not all the required keys were submitted in the info.json or request payload. Please check request values for this product.
2214
Error - Product not activated for this account
Product is deactivated on your account. Contact support to activate the product.
2217
Error - Invalid Product
Update the job_type to 4 and ensure you have send all the required request values for this product.
2220
Error - Production is not enabled for this account.
You have not completed your KYC. Please complete your KYC with Smile ID.
2221
Error - Invalid token
Only applicable to Web SDK jobs. Generate a valid token and re-run the job.

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
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
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
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
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 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.
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 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.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",
"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. 1.
    Approved (or Pass) This means that all applicable Actions passed and the overall job was approved.
  2. 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. 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
The format of one of the request values was wrong. Please check request values for this product.
2205
Error - You are not authorized to do that
An invalid signature was used to sign the request. Read more on how to troubleshoot this error here.
2207
Error - Enrolled user is disabled
You attempted authenticating a disabled user, enable the user then re-run the job or send the user_id of an active user.
2208
Error - Enrolled user was deleted from the system
You attempted authenticating a deleted user, send the user_id of an active user or re-enroll the user.
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
Ther user_id has been flagged for re-enrollment. Either turn off the re-enrollment flag or re-enroll the user before attempting to authentication.
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
Not all the required keys were submitted in the info.json or request payload. Please check request values for this product.
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
The user_id does not have a selfie on file. Before you can authenticate, you need to perform either a Document Verification, Biometric Registration or SmartSelfie™ Registration job for the user_id.
2217
Error - Invalid Product
Update the job_type to 2 and ensure you have send all the required request values for this product.
2220
Error - Production is not enabled for this account
You have not completed your KYC. Please complete your KYC with Smile ID.
2221
Error - Invalid token
Only applicable to Web SDK jobs. Generate a valid token and re-run the job.

Product Specific Result Codes and Texts

Code
Text
Description
Category
0001
Data Invalid
One of the required input is invalid.