Enhanced KYC + SmartSelfie™

Overview

The Enhanced KYC + SmartSelfie™ product lets you verify the ID information of your user and confirm that the ID actually belongs to the user, this is achieved by comparing the user's SmartSelfie™ (a combination of grayscale liveness images and one colored image) to either the photo of the user on file in an ID authority database or a photo of their ID card.

Integration Options

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

Request Values

You need to perform two steps to use this product:
  • Make a request to Smile Identity for a job to be performed
  • Upload the requirements for the job

Making a Job Request - Prep Upload

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 "1".
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

1
{
2
"file_name": "attachments.zip",
3
"signature": "<calculated signature>",
4
"timestamp": "<timestamp e.g. 2021-08-12T17:57:00.614879>",
5
"smile_client_id": "<partner id>",
6
"partner_params":
7
{
8
"job_type": "1"
9
"job_id":"job_09876",
10
"user_id":"user_12345",
11
},
12
"model_parameters": {},
13
"callback_url": "https://<your callback URL>/"
14
}
Copied!
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
1
{
2
"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",
3
"ref_id": "<partner_id>-<smile_job_id>-<random hash>",
4
"smile_job_id": "0000000001",
5
"camera_config": "null", ---sdk specific---
6
"code": "2202"
7
}
Copied!
400: Bad Request
Trying to use a job_id in partner_params that has already been used
1
{
2
"error": "Job already exists. Did you mean to set the retry flag to true?",
3
"code": "2215"
4
}
Copied!

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
id_info
to view the list of required fields per id type see supported ID types
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
1
{
2
"package_information":
3
{
4
"apiVersion": {
5
"buildNumber": 0,
6
"majorVersion": 2,
7
"minorVersion": 0
8
}
9
},
10
"id_info":
11
{
12
"dob":"<dob in ID type specific format>",
13
"country":"<country code e.g. KE>",
14
"entered":true <job type 1> | false,
15
"id_type":"smile ID type keyword e.g. NATIONAL_ID",
16
"id_number":"00000000",
17
"last_name":"Joe",
18
"first_name":"Leo",
19
"middle_name":"Doe"
20
},
21
"images": [
22
{
23
<use either image or file_name, both cannot be used at the same time>
24
"image_type_id": <0 | 2>,
25
"image": "<base64 string of image>",
26
"file_name": "<name of file in the zip that will be uploaded>"
27
}
28
]
29
}
Copied!

How Smile ID Processes the Job

Action
Description
ID lookup in ID authority database
ID information is queried in ID authority database
Proof of life & spoof detection
Performed on user submitted selfie
Selfie compares
If photo is available in ID authority database, Selfie is compared to photo on file else Selfie is compared to user submitted ID card photo

Return Values

The full list of keys and possible return values are highlighted below:
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.
“1”
PartnerParams.user_id
String
A unique reference defined by you to keep track of the user
ResultCode
String
Numeric value of the job outcome.
For a list of potential error codes see here.
ResultText
String
Textual value of the job outcome. Human readable value for the result.
List of all result text is listed here.
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_Compare
String
If the Smile ID system can not automatically decide on the face compares it will be reviewed by humans and the result will be displayed here
“Passed”
“Failed”
“Unable to Determine”
“Not Applicable”
Human_Review_Liveness_Check
String
If the Smile ID system can not automatically decide on the liveness of the user submitted selfie, it will 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”
Return_Personal_Info
String
Return user’s PII from ID authority
“Returned”
“Not Returned”
“Not Applicable”
Selfie_Provided
String
User provided a usable selfie
Selfie_To_ID_Authority_Compare
String
Compare user submitted selfie to government ID authority photo
“Completed”
“Under Review”
“ID Authority Photo Not Available”
“Not Applicable”
Selfie_To_ID_Card_Compare
String
Compare user submitted to user submitted ID card photo
“Completed”
“Under Review”
“Not Applicable”
Verify_ID_Number
String
Query ID number in the ID authority database
“Verified”
“Not Verified”
“Issuer Unavailable”
“Not Applicable”

Example JSON Response

1
{
2
"Actions": {
3
"Liveness_Check": "Passed",
4
"Register_Selfie": "Approved",
5
"Selfie_Provided": "Passed",
6
"Verify_ID_Number": "Verified",
7
"Human_Review_Compare": "Passed",
8
"Return_Personal_Info": "Returned",
9
"Selfie_To_ID_Card_Compare": "Not Applicable",
10
"Human_Review_Update_Selfie": "Not Applicable",
11
"Human_Review_Liveness_Check": "Passed",
12
"Selfie_To_ID_Authority_Compare": "Completed",
13
"Update_Registered_Selfie_On_File": "Not Applicable",
14
"Selfie_To_Registered_Selfie_Compare": "Not Applicable"
15
},
16
"ConfidenceValue": "99.000000",
17
"PartnerParams": {
18
"job_id": "KE_TEST_100",
19
"job_type": "1",
20
"user_id": "KE_TESTTEST_100"
21
},
22
"ResultCode": "1210",
23
"ResultText": "Enroll User",
24
"SmileJobID": "0000056574",
25
"Source": "WebAPI",
26
"timestamp": "2021-05-06T08:48:50.763Z",
27
"signature": "..."
28
}
Copied!

Evaluating the Results

Actions performed on the product are not completed at the same time, so we send results to your callback as they are ready. Also, if the Smile ID system can not automatically make a decision on an action it is passed to human reviewers, the system decision is sent via callback pending the time the reviewers make a final decision.
You can get the results of the job anytime by using the Job Status endpoint. Read more about the Job Status endpoint in the Utilities section of any integration option of your choice.

Result Codes and Result Texts

Result codes details what the current (or final) result of a job is. Result Codes for all jobs fall into one of three categories:
  1. 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 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
Description
Category
0001
Data Invalid
Rejected
0903
Zip Corrupt
The uploaded Zip file is corrupted.
Rejected
0907 (deprecated)
FAIL - Possible Spoof - Strict Setting
The machine detected a possible spoof and product was ran as strict.
Rejected
2405
Error - "You are not authorized to do that" *
An invalid signature was used to sign the request.
-
2314
Error - No Zip File Received
No Zip files was uploaded.
-
2203
Error - Invalid JSON
The info.json file in the Zip is not properly structured. Ensure all keys are present and properly named.
-
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.
-
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.
-
2220
Error - Production is not enabled for this account. Please complete your KYC with Smile Identity.
You have not completed your KYC.
-
2212
Error - Invalid job type **
An invalid value was inputted in the job_type key. Change the value to "1".
-
2215
Error - Job already exists for job_id
An existing job_id was inputted. Enter a unique job id.
-
* - read more on how to troubleshoot this error here ** - set Job Type to "1"

Product Specific Result Codes and Texts

Code
Text
Description
Category
0911
No Face Found
There was no face found in the uploaded selfie. Upload an image with a face.
Rejected
0912
Image Quality Judged Too Poor
The uploaded selfie quality was too poor. Upload a higher quality selfie.
Rejected
0810
Enroll User
Machine Judgement - PASS
Images matched and no spoof detected on the selfie.
Approved
0811
Failed Enroll
Machine Judgement - FAIL - Compare Rejected
Images did not match and job was therefore rejected.
Rejected
0812
Machine Judgement - Pure Provisional
Waiting on document reviewer's decision.
Provisionally Approved
0813 (deprecated)
Failed Enroll
Machine Judgement - FAIL, Possible Spoof - Strict/Custom Settings
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
0814
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.
Provisionally Approved
0815
Machine Judgement - Provisional - Compare Unsure
The machine is not sure if both images match, so a document reviewer will compare.
Provisionally Approved
1210
Enroll User
Human Judgement - PASS
The document reviewer marked that both images are of the same person and no spoof was detected.
Approved
1211
Failed Enroll
Human Judgement - FAIL - Human Compare Failed
The document reviewer marked that both images are different persons.
Rejected
1212
Failed Enroll
Human Judgement - 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
1213
Human Judgement - Provisional - Liveliness Unsure
The document reviewer is not sure if there is a possible fraud attempt on the Selfie.
Inconclusive
1012
ID Verification Success
The ID info is valid and was found in the ID authority database.
Provisionally Approved
1013
Invalid ID
The ID info was not found in the ID authority database.
Rejected
1014
Unsupported ID number format
The ID number submitted was of an invalid format. Please use our regex samples as a guide.
Rejected
1015
Error - Queried Database Unavailable *
The ID authority is unavailable.
0908
Error - Issuer not available
The ID authority is unavailable.
1016
Error - Need to Activate Product
You do not have access to the ID Type. Please contact support for more information.
2209
Error - This user is already enrolled with user_id
An existing user_id was inputted. Enter a unique user id.
* - If the queried ID info was issued in Kenya, the job fails and no further processing is performed
Last modified 23h ago