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. 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. 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. Perform an Authentication

    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

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

The request body will be of type binary (the zip file)

Info.json file

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:

* 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

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

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

Result Codes and Texts Specific to Registering a User

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

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

The request body will be of type binary (the zip file)

Info.json file

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:

* 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",
  "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

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

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

Product Specific Result Codes and Texts

Last updated