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):
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)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:
Register a User
Make a job request to register a user (ensure you take note of the
user_id
)
Perform an Authentication
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
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 | 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
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
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:
Depending on the image_type_id one of the other parameters will be an empty string (“”) |
Info.json Example
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
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:
Approved (or Pass) This means that all applicable Actions passed and the overall job was approved.
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, aPending 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.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 |
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 |
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
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 | 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
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
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:
Depending in the image_type_id one of the other parameters will be an empty string (“”) |
Info.json Example
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
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:
Approved (or Pass) This means that all applicable Actions passed and the overall job was approved.
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, aPending 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.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 |
2208 | Error - Enrolled user was deleted from the system | You attempted authenticating a deleted user, send the |
2210 | Error - No enrolled user found | The |
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 | 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 |
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. | |
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 |
Last updated