SmartSelfie™ Compare

The SmartSelfie™ Compare product lets you match and authenticate a genuine user's selfie with an existing photo on file.

Overview

The SmartSelfie™ Compare product lets you match and authenticate a genuine user's selfie with an existing photo on file.

In one step, you submit both: 1. the user's selfie and liveness images and 2. the image on file (eg. government authority image).

With SmartSelfie™ Compare, a user will enrolled (registered) and Authenticated in one go instead of the two step process of SmartSelfie™ Authentication .

Integration Options

Available on Rest API.

You can capture face images using the mobile and web SDKs and then submit via the REST APIs. To do this, see

Using the SmartSelfie™ Compare Product

Follow the steps below to perform a SmartSelfie™ Compare:

1. Make a job request that has your selfie and comparison photo

2. Upload the job requirements

3. Evaluate your result

Making a Request

This API is designed to be more RESTFUL to ensure standardised consistency and stateless API implementation. Hence, it differs from our existing biometric products in two main ways:

1. It uses header-based authentication instead of body-based authentication. This means you will now add your authorisation params (timestamp, partner-id, and signature) in the HTTP-header. This

2. The responses are always synchronous. You can add a callback and recieve responses in the previous smile format. The synchronous nature of these responses means there are NO HUMAN REVIEWS at the submission stage. Hence there will be no PENDING or PROVISIONAL RESULTS.

Request Type and URLs

Request Type: POST

Environment	URL
Sandbox	https://testapi.smileidentity.com/v2/smart-selfie-compare
Production	https://api.smileidentity.com/v2/smart-selfie-compare

Request Header

Key	Value	Required	Description
Content-Type	multipart/form-data	Yes
SmileID-Partner-ID	{{your_partner_id eg. 0001}}	Yes	This is your partner id which can be found on the side navigation panel of the Smile ID partner portal
SmileID-Timestamp	{{your_calculated_time_stampp eg. 2024-08-19T11:35:07.809Z}}	Yes	The timestamp that was used to calculate the sec_key (in ISO date/time format)
SmileID-Request-Signature	{{your calculated_signature}}	Yes	Your calculated access signature

Request Body

Keys	Type	Required	Description
user_id	string	Yes	The ID of the user to enroll after face comparison
selfie_image	File	Yes	Selfie image
comparison_image	File	Yes	Comparison image
comparison_image_type**	string	Yes	The type of comparison image it can be one of ID_PHOTO: photos from ID Authority PORTRAIT - A user's selfie or captured by an agent using DOCUMENT - photo of an ID document
liveness_images	File	Yes	There is a minimum of 4 and max of 8 liveness images you must send. It is recommended you send 8 liveness for a more validation process
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
allow_new_enroll	string {true or default: false}	No	A flag to re-enroll an existing user identified by the param user_id allow_new_enroll has a default value of false.
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
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)

Note: You will pass each liveness image as a separate parameter per image. in the form data. Do not pass it as an array collection

** Specifying the the right image type is important for successful outcomes. There is a difference between how we process ID_PHOTO and PORTRAIT. ID Authority images (ID_PHOTO) might contain artefacts (such as watermarks, stamps etc) that we automatically make exceptions for.

Example Request

A sample request is as follows:

curl --request POST '/v2/smart-selfie-compare' \
--header 'Content-Type: multipart/form-data' \
--header 'SmileID-Timestamp: 2024-05-24T09:45:43.044Z' \
--header 'SmileID-Partner-ID: 0000' \
--header 'SmileID-Request-Signature: xxxx' \
--form 'user_id="user-id-uuid"' \
--form 'selfie_image=@"/somefilepath/selfie.jpg"' \
--form 'comparison_image="ID_PHOTO"' \
--form 'liveness_images=@"/somefilepath/liveness_0001.jpg"' \
--form 'liveness_images=@"/somefilepath/liveness_0002.jpg"' \
--form 'liveness_images=@"/somefilepath/liveness_0003.jpg"' \
--form 'liveness_images=@"/somefilepath/liveness_0004.jpg"' \
--form 'liveness_images=@"/somefilepath/liveness_0005.jpg"' \
--form 'liveness_images=@"/somefilepath/liveness_0006.jpg"' \
--form 'callback_url="https://some_webhook"' \
--form 'partner_params={"job_id": "firstprodfastauth6", "user_id": "user-id-uuid", "job_type":"3"}' \
--form 'allow_new_enroll="True"'

Results 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
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.
PartnerParams.user_id	String	A unique reference defined by you to keep track of the user
Code	String	Numeric value of the job outcome.	Full list of result codes below
Text	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
Liveness_Check	String	Liveness check on user provided liveness images	“Passed” “Failed”
Selfie_Check	String	Passive liveness check on the user provided selfie	“Passed” “Failed”
code	String	The error codes that match with	“Approved” “Rejected” “Provisionally Approved” “Not Applicable”
Selfie_Provided	String	User provided a usable selfie	"Passed" "Failed"

The response includes detailed information about the biometric checks performed, such as liveness checks and face verification, along with the results and any relevant metadata.

Example Successful Response: 200: OK

A successful API response (usually 0840 - match and 0841 - no match) follows the following structure:

{
  "code": "0840",
  "created_at": "2021-08-01T12:00:00Z",
  "job_type": "smart_selfie_compare",
  "message": "Match",
  "job_id": "123456",
  "user_id": "user-12345602--234r",
  "partner_id": "123",
  "partner_params": {
    "job_id": "job-1234-9876",
    "user_id": "user-12345602--234r"
  },
  "updated_at": "2021-08-01T12:00:00Z",
  "status": "approved"
}

Sample Failed Response 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"
}

A successful callback response as the following structure

 {
    "ResultCode": "Code indicating the result",
    "ResultText": "Description of the result",
    "IsFinalResult": "true",
    ...additional fields
  }

Validations

• We perform field validations to ensure all required fields are parsed in the form.

{
    "code": "2413",
    "error": "selfie_image is required.",
    "success": false
}

• For internal server errors we return the error

{
  "code": "2210",
  "error": "System Error",
  "success": false
}

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. Matched (or Pass) This means that all applicable Actions passed and the overall job was approved.

2. No Match (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.

Specific Result Codes and Texts

Code	Text	Description	Category
0001	Data Invalid	One of the required input is invalid.
0001	System Error	An unknown system error occurred while processing the job.
0840	Face Match	Comparison between the images matched.	Approved
0841	No Match - - No Face Match	Images did not match and therefore job was rejected.	Rejected
0941	No Match - The compared images are identical.	The comparison image and selfie image are identical or the same image	Rejected

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
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	Wrong job type. This user is already enrolled.	This user is already enrolled. use a unique user Id or allow_new_enroll
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.
2220	Error - Production is not enabled for this account	You have not completed your KYC. Please complete your KYC with Smile ID.
2413	Inputs submitted are incorrect	There are errors with the required inputs eg. Liveness images or comparison images