> For the complete documentation index, see [llms.txt](https://legacy-docs.usesmileid.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://legacy-docs.usesmileid.com/products/for-individuals-kyc/biometric-authentication.md).

# SmartSelfie™ Authentication

## Overview

SmartSelfie™ Authentication verifies a returning user’s identity by comparing a newly captured selfie to a reference image already registered in Smile ID's system. A reference selfie can come from a previous successful [Biometric KYC](/products/for-individuals-kyc/biometric-kyc.md), [Document Verification](/products/for-individuals-kyc/document-verification.md), or [SmartSelfie™ Compare](/products/for-individuals-kyc/smartselfie-tm-compare.md) job.

{% hint style="info" %}
**SmartSelfie™ Authentication requires a pre-existing reference selfie. If the user hasn’t completed any of the jobs mentioned above, please perform a** [**SmartSelfie™ Registration**](#registering-a-user) **first to capture and register their selfie.**
{% endhint %}

## Integration Options

Available on [Mobile](/integration-options/mobile.md), [Server-to-Server](/integration-options/server-to-server.md) libraries and [Rest API](/integration-options/rest-api.md).

## Performing an Authentication

### Prerequisite

To perform SmartSelfie™ Authentication, you must provide a `user_id` that has already been used in a successful job where a reference selfie was captured.

This means the user must have previously completed one of the following:

* [Biometric KYC](/products/for-individuals-kyc/biometric-kyc.md)
* [Document Verification](/products/for-individuals-kyc/document-verification.md)
* [SmartSelfie™ Compare](/products/for-individuals-kyc/smartselfie-tm-compare.md)

If no such job exists for the user, please register them first by performing a [SmartSelfie™ Registration](#registering-a-user).

Once you have a valid `user_id` from one of these jobs, you can follow the instructions below to authenticate the user.

### **Make a Job Request**

**Request Type**: POST

| Environment | URL                                           |
| ----------- | --------------------------------------------- |
| Sandbox     | <https://testapi.smileidentity.com/v1/upload> |
| Production  | <https://api.smileidentity.com/v1/upload>     |

<table data-header-hidden><thead><tr><th width="213">Keys</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>Keys</td><td>Type</td><td>Required</td><td>Description</td></tr><tr><td>source_sdk</td><td>string</td><td>Yes</td><td>The integration option you are using. For rest api send the value as <code>rest_api</code></td></tr><tr><td>source_sdk_version</td><td>string</td><td>Yes</td><td>The version of the integration option you are using</td></tr><tr><td>signature</td><td>string</td><td>Yes</td><td>Your calculated access signature</td></tr><tr><td>timestamp</td><td>string</td><td>Yes</td><td>The timestamp that was used to calculate the signature in ISO 8601 extended format</td></tr><tr><td>smile_client_id</td><td>string</td><td>Yes</td><td>This is your partner id which can be found on the side navigation panel of the <a href="https://portal.usesmileid.com/partner/dashboard">Smile ID partner portal</a></td></tr><tr><td>partner_params</td><td>object</td><td>Yes</td><td>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</td></tr><tr><td>partner_params.job_type</td><td>string</td><td>Yes</td><td>The type of job you want to perform. This will be set to <code>2</code>.</td></tr><tr><td>partner_params.job_id</td><td>string</td><td>Yes</td><td>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</td></tr><tr><td>partner_params.user_id</td><td>string</td><td>Yes</td><td>The user ID of an existing user who has successfully been registered.</td></tr><tr><td>callback_url</td><td>string</td><td>Yes</td><td>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)</td></tr></tbody></table>

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

```json
{
  "callback_url": "https://<partner side callback URL>/",
  "partner_params": {
    "job_id": "job_09876",
    "job_type": 2,
    "user_id": "<user_id from a previous successful onboarding job>"
  },
  "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*

```json
{
    "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*

```json
{
  "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

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

{% hint style="success" %}

* the **info.json** file only (if images are inline i.e. supplied as base64 encoded strings)
* or both an info.json file and the raw .jpg image files (if the image files themselves are uploaded).
  {% endhint %}

{% hint style="danger" %}
Please do not put the info.json file inside a folder called attachments before zipping.
{% endhint %}

<figure><img src="/files/ENZ8LeQYjaY9sumCEqXg" alt=""><figcaption><p>zip file contains only the info.json file</p></figcaption></figure>

| Parameter            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| package\_information | just use the example below                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| images               | <p>not used if files are uploaded. for image list structure, read more on <a href="/pages/-MaeazELMSJgL6ojO1Jg">Smile ID image types</a></p><p><br>in an image item all 3 parameters will exist:</p><p><br>{</p><p>"image\_type\_id": 2,</p><p>"image": "\<base64 string of image>",</p><p>"file\_name": "\<name of file in the zip that will be uploaded>"</p><p>}</p><p><br>Depending in the image\_type\_id one of the other parameters will be an empty string ("")</p> |

**Info.json Example**

```json
{
  "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:

<table data-header-hidden><thead><tr><th>Name</th><th width="150">Type</th><th>Description</th><th>Return Values</th></tr></thead><tbody><tr><td><strong>Name</strong></td><td><strong>Type</strong></td><td><strong>Description</strong></td><td>Return Values</td></tr><tr><td>ConfidenceValue (deprecated)</td><td>String</td><td>Smile ID’s confidence that the user should be registered. Values are between 0% - 100%</td><td>0% - 100%</td></tr><tr><td>PartnerParams.job_id</td><td>String</td><td>A unique reference defined by you to keep track of the job</td><td></td></tr><tr><td>PartnerParams.job_type</td><td>String</td><td>The type of job you performed.</td><td>2</td></tr><tr><td>PartnerParams.user_id</td><td>String</td><td>A unique reference defined by you to keep track of the user</td><td></td></tr><tr><td>ResultCode</td><td>String</td><td>Numeric value of the job outcome.</td><td>Full list of result codes <a href="#result-codes-and-result-texts-1">below</a></td></tr><tr><td>ResultText</td><td>String</td><td>Textual value of the job outcome. Human readable value for the result.</td><td>Full list of result text <a href="#result-codes-and-result-texts-1">below</a>.</td></tr><tr><td>SmileJobID</td><td>String</td><td>The Smile internal reference number for the job</td><td></td></tr><tr><td><strong>Actions</strong></td><td>Object</td><td>The JSON object contains the results of checks Smile ID performed on the job</td><td></td></tr><tr><td>Human_Review_Liveness_Check</td><td>String</td><td>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</td><td><p>“Passed”</p><p>“Failed”</p><p>“Unable To Determine”</p><p>“Under Review”</p><p>“Not Applicable”</p></td></tr><tr><td>Liveness_Check*</td><td>String</td><td>Liveness check on user provided liveness images</td><td><p>“Passed”</p><p>“Failed”</p><p>“Under Review”</p><p>“Not Applicable”</p></td></tr><tr><td>Selfie_Check</td><td>String</td><td>Passive liveness check on user provided selfie</td><td><p>“Passed”</p><p>“Failed”</p><p>“Under Review”</p><p>“Not Applicable”</p></td></tr><tr><td>Human_Review_Selfie_Check</td><td>String</td><td>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</td><td><p>“Passed”</p><p>“Failed”</p><p>“Unable To Determine”</p><p>“Under Review”</p><p>“Not Applicable”</p></td></tr><tr><td>Selfie_Provided</td><td>String</td><td>User provided a usable selfie</td><td><p>"Passed"</p><p>"Failed"</p></td></tr><tr><td>Selfie_To_Registered_Selfie_Compare</td><td>String</td><td>Compare user submitted selfie to user's Selfie on file</td><td><p>“Completed”</p><p>“Under Review”</p><p>“Not Applicable”</p></td></tr></tbody></table>

\* If a single selfie image is provided, the system will only perform a `Selfie_Check`

{% hint style="info" %}
ConfidenceValue is deprecated, please use ResultCode to determine outcome of the job.
{% endhint %}

**Example JSON Response**

```json
{
  "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

| **Action**                      | Description                                                     |
| ------------------------------- | --------------------------------------------------------------- |
| Proof of life & spoof detection | Performed on user submitted selfie                              |
| Selfie compare                  | 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:

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.

{% hint style="info" %}
Prefix for error codes may also be **`23xx`** or **`24xx`**
{% endhint %}

| 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 ](#make-a-job-request)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](/further-reading/troubleshooting/troubleshooting-error-2204-and-2205-youre-not-authorized-to-do-that.md).                                                                                                                            |
| 2207 | Error - Enrolled user is disabled                   | You attempted authenticating a disabled user, [enable the user](/further-reading/faqs/how-to-re-enroll-or-delete-a-user.md) then re-run the job or send the `user_id` of an active user.                                                                                                                                                   |
| 2208 | Error - Enrolled user was deleted from the system   | You attempted authenticating a deleted user, send the `user_id` of an active user or [re-enroll the user](/further-reading/faqs/how-to-re-enroll-or-delete-a-user.md).                                                                                                                                                                     |
| 2210 | Error - No enrolled user found                      | The `user_id` does not belong to an enrolled user. Confirm the `user_id` then re-run the authentication.                                                                                                                                                                                                                                   |
| 2211 | Error - Enrolled user must complete re-enrollment   | Ther user\_id has been flagged for re-enrollment. Either [turn off the re-enrollment flag](/further-reading/faqs/how-to-re-enroll-or-delete-a-user.md) 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](#make-a-job-request-1) 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 `job_id`             | 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](/products/for-individuals-kyc/document-verification.md), [Biometric Registration](/products/for-individuals-kyc/biometric-kyc.md) or [SmartSelfie™ Registration](#registering-a-user) job for the user\_id. |
| 2217 | Error - Invalid Product                             | Update the `job_type` to 2 and ensure you have send all the required [request values](#make-a-job-request-1) for this product.                                                                                                                                                                                                             |
| 2220 | Error - Production is not enabled for this account  | You have not completed your KYC. Please complete your [KYC with Smile ID.](/getting-started/complete-your-kyc.md)                                                                                                                                                                                                                          |
| 2221 | Error - Invalid token                               | Only applicable to [Web SDK](/integration-options/web-mobile-web/web-integration.md) 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              | <p>Authenticate User</p><p>Machine Judgement - PASS</p>                          | Comparison between the images matched.                                                                                                                                                    | Approved               |
| 0821              | <p>Failed Authentication</p><p>Machine Judgement - FAIL - COMPARISON</p>         | 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) | <p>Failed Authentication</p><p>Machine Judgement - FAIL - Possible Spoof</p>     | 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              | <p>Authenticate User</p><p>Human Judgement - PASS</p>                            | The document reviewer marked that both images are of the same person.                                                                                                                     | Approved               |
| 1221              | <p>Failed Authentication</p><p>Human Judgement - FAIL - Human Compare Failed</p> | The document reviewer marked that both images are different persons.                                                                                                                      | Rejected               |
| 1222              | <p>Failed Authentication</p><p>Human Judgement - FAIL - Spoof Detected</p>       | 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               |

## SmartSelfie™ Registration

If the user doesn’t have a reference selfie on file, you can perform a SmartSelfie™ Registration to capture and save their selfie for future authentication attempts. During this process, we will also perform liveness checks before registering the selfie.

To complete the registration, you’ll need to provide:

* A clear selfie of the user. We recommend using our [Mobile](/integration-options/mobile.md) or [Web SDKs](/integration-options/web-mobile-web.md) to capture a high-quality SmartSelfie™ (selfie and liveness images).
* A new `user_id`. This unique identifier will be required when performing future authentications for the user.

## Registering a User

### Make a Job Request

**Request Type**: POST

| Environment | URL                                           |
| ----------- | --------------------------------------------- |
| Sandbox     | <https://testapi.smileidentity.com/v1/upload> |
| Production  | <https://api.smileidentity.com/v1/upload>     |

<table data-header-hidden><thead><tr><th width="217">Keys</th><th width="150">Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>Keys</td><td>Type</td><td>Required</td><td>Description</td></tr><tr><td>source_sdk</td><td>string</td><td>Yes</td><td>The integration option you are using. For rest api send the value as "rest_api"</td></tr><tr><td>source_sdk_version</td><td>string</td><td>Yes</td><td>The version of the integration option you are using</td></tr><tr><td>signature</td><td>string</td><td>Yes</td><td>Your calculated access signature</td></tr><tr><td>timestamp</td><td>string</td><td>Yes</td><td>The timestamp that was used to calculate the sec_key (in ISO date/time format)</td></tr><tr><td>smile_client_id</td><td>string</td><td>Yes</td><td>This is your partner id which can be found on the side navigation panel of the <a href="https://portal.usesmileid.com/partner/dashboard">Smile ID partner portal</a></td></tr><tr><td>partner_params</td><td>object</td><td>Yes</td><td>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</td></tr><tr><td>partner_params.job_type</td><td>string</td><td>Yes</td><td>The type of job you want to perform. This will be set to 4.</td></tr><tr><td>partner_params.job_id</td><td>string</td><td>Yes</td><td>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</td></tr><tr><td>partner_params.user_id</td><td>string</td><td>Yes</td><td>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</td></tr><tr><td>callback_url</td><td>string</td><td>Yes</td><td>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)</td></tr></tbody></table>

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

```json
{
  "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*

```json
{
    "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*

```json
{
  "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

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

{% hint style="success" %}
The zip file contains

* the **info.json** file only (if images are inline i.e. supplied as base64 encoded strings)
* or both an info.json file and the raw .jpg image files (if the image files themselves are uploaded).
  {% endhint %}

{% hint style="danger" %}
Please do not put the info.json file inside a folder called attachments before zipping.
{% endhint %}

<figure><img src="/files/ENZ8LeQYjaY9sumCEqXg" alt=""><figcaption><p>zip file contains only the info.json file</p></figcaption></figure>

| Parameter            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| package\_information | just use the example below                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| images               | <p>not used if files are uploaded. for image list structure, read more on <a href="/pages/-MaeazELMSJgL6ojO1Jg">Smile ID image types</a></p><p><br>in an image item all 3 parameters will exist:<br><br><code>{</code></p><p><code>"image\_type\_id": 2,</code></p><p><code>"image": "\<base64 string of image>",</code></p><p><code>"file\_name": "\<name of file in the zip that will be uploaded>"</code></p><p><code>}</code></p><p><br>Depending on the image\_type\_id one of the other parameters will be an empty string (“”)</p> |

**Info.json Example**

```json
{
  "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:

<table data-header-hidden><thead><tr><th>Name</th><th width="150">Type</th><th>Description</th><th>Return Values</th></tr></thead><tbody><tr><td><strong>Name</strong></td><td><strong>Type</strong></td><td><strong>Description</strong></td><td>Return Values</td></tr><tr><td>ConfidenceValue</td><td>String</td><td>Smile ID’s confidence that the user should be registered. Values are between 0% - 100%</td><td>0% - 100%</td></tr><tr><td>PartnerParams.job_id</td><td>String</td><td>A unique reference defined by you to keep track of the job</td><td></td></tr><tr><td>PartnerParams.job_type</td><td>String</td><td>The type of job you performed.</td><td>4</td></tr><tr><td>PartnerParams.user_id</td><td>String</td><td>A unique reference defined by you to keep track of the user</td><td></td></tr><tr><td>ResultCode</td><td>String</td><td>Numeric value of the job outcome.</td><td>Full list of result codes <a href="#result-codes-and-result-texts">below</a></td></tr><tr><td>ResultText</td><td>String</td><td>Textual value of the job outcome. Human readable value for the result.</td><td>Full list of result text <a href="#result-codes-and-result-texts">below</a>.</td></tr><tr><td>SmileJobID</td><td>String</td><td>The Smile internal reference number for the job</td><td></td></tr><tr><td><strong>Actions</strong></td><td>Object</td><td>The JSON object contains the results of checks Smile ID performed on the job</td><td></td></tr><tr><td>Human_Review_Liveness_Check</td><td>String</td><td>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</td><td><p>“Passed”</p><p>“Failed”</p><p>“Unable To Determine”</p><p>“Under Review”</p><p>“Not Applicable”</p></td></tr><tr><td>Liveness_Check*</td><td>String</td><td>Liveness check on user provided liveness images</td><td><p>“Passed”</p><p>“Failed”</p><p>“Under Review”</p><p>“Not Applicable”</p></td></tr><tr><td>Selfie_Check</td><td>String</td><td>Passive liveness check on the user provided selfie</td><td><p>“Passed”</p><p>“Failed”</p><p>“Under Review”</p><p>“Not Applicable”</p></td></tr><tr><td>Human_Review_Selfie_Check</td><td>String</td><td>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</td><td><p>“Passed”</p><p>“Failed”</p><p>“Unable To Determine”</p><p>“Under Review”</p><p>“Not Applicable”</p></td></tr><tr><td>Register_Selfie</td><td>String</td><td>Register selfie of user</td><td><p>“Approved”</p><p>“Rejected”</p><p>“Provisionally Approved”</p><p>“Not Applicable”</p></td></tr><tr><td>Selfie_Provided</td><td>String</td><td>User provided a usable selfie</td><td><p>"Passed"</p><p>"Failed"</p></td></tr></tbody></table>

{% hint style="info" %}
\* If a single selfie image is provided, the system will only perform a `Selfie_Check`
{% endhint %}

**Example JSON Response**

```json
{
  "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

| **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:

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.

{% hint style="info" %}
Prefix for error codes may also be **`23xx`** or **`24xx`**
{% endhint %}

| 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 ](#make-a-job-request)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](/further-reading/troubleshooting/troubleshooting-error-2204-and-2205-youre-not-authorized-to-do-that.md). |
| 2209 | Error - User is already enrolled                    | The job was run with a duplicate `user_id.` Send the job with a unique `user_id`.                                                                                                                               |
| 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](#make-a-job-request) 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 `job_type` to 4 and ensure you have send all the required [request values](#make-a-job-request) for this product.                                                                                    |
| 2220 | Error - Production is not enabled for this account. | You have not completed your KYC. Please complete your [KYC with Smile ID.](/getting-started/complete-your-kyc.md)                                                                                               |
| 2221 | Error - Invalid token                               | Only applicable to [Web SDK](/integration-options/web-mobile-web/web-integration.md) 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              | <p>Enroll User</p><p>PASS - Machine Judgement</p>                    | Machine passed Selfie - no spoof detected and image contains a face.                                                                                                                   | Approved                                                             |
| 0841              | <p>Failed Enroll</p><p>FAIL - Possible Spoof - Machine Judgement</p> | 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              | <p>Enroll User</p><p>PASS - Human Judgement</p>                      | The human reviewer did not find any fraud attempts on the Selfie.                                                                                                                      | Approved                                                             |
| 1241              | <p>Failed Enroll</p><p>FAIL - Image Unusable</p>                     | The human reviewer marked the Selfie as unusable either because the Selfie is too dark or too blurry                                                                                   | Rejected                                                             |
| 1242              | <p>Failed Enroll</p><p>Spoof detected - Human Judgement</p>          | 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                                                             |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://legacy-docs.usesmileid.com/products/for-individuals-kyc/biometric-authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.