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

EnvironmentURL

Sandbox

https://testapi.smileidentity.com/v2/smart-selfie-compare

Production

https://api.smileidentity.com/v2/smart-selfie-compare

Request Header

KeyValueRequiredDescription

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

KeysTypeRequiredDescription

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

CodeTextDescriptionCategory

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

CodeTextDescription

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

PreviousSmartSelfie™ AuthenticationNextSmile Secure

Last updated