> 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-kyc.md).

# Biometric KYC

## Overview

The Biometric KYC 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 liveness images and a primary image) to the photo of the user on file in an ID authority database.

## Integration Options

Available via the [Rest API](/integration-options/rest-api.md), [Mobile](/integration-options/mobile.md), [Server to Server](/integration-options/server-to-server.md) and [Web SDK](/integration-options/web-mobile-web/web-integration.md).

## Request Values

You need to perform two steps to use this product:

* Make a request to Smile ID for a job to be performed
* Upload the requirements for the job

### Making a Job Request - Prep Upload

**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="228">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 "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 signature (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>{job_type</td><td>string</td><td>Yes</td><td>The type of job you want to perform. This will be set to 1.</td></tr><tr><td>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>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>model_parameters</td><td>string</td><td>No</td><td>This parameter is specific to mobile SDK, can be left as an empty JSON object</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://<your callback URL>/",
  "model_parameters": {},
  "partner_params": {
    "job_id": "job_09876",
    "job_type": 1,
    "user_id": "user_12345"
  },
  "signature": "<calculated signature>",
  "smile_client_id": "<partner id>",
  "source_sdk_version": "1.0.0",
  "source_sdk": "rest_api",
  "timestamp": "<timestamp e.g. 2021-08-12T17:57:00.614879>"
}
```

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*

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

The images can either be parsed inline as a base64 encoded string or the image files themselves can be zipped with the info.json file. Only .jpg file type is supported.

**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 | <p>This contains information about the rest api you’re calling. We recommend you use the following as the package\_information:</p><p><code>"package\_information":</code></p><p><code>{</code></p><p><code>"apiVersion": {</code></p><p><code>"buildNumber": 0,</code></p><p><code>"majorVersion": 2,</code></p><p><code>"minorVersion": 0</code></p><p><code>}</code></p><p><code>}</code></p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| id\_info             | <p>The country and id type you want to verify. The uploaded ID card image must match the country and id type you specify in this json object. To view the list of supported documents see <a href="/pages/-Ma8myUwif8S8KMRDnYS">supported ID types</a> in the docs.<br></p><p><code>"id\_info":</code></p><p><code>{</code></p><p><code>"country":"\<country code e.g. KE>",</code></p><p><code>"id\_type":"\<smile ID type keyword e.g. NATIONAL\_ID>"</code></p><p><code>}</code></p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| images               | <p>The images required for the biometric kyc job. There are 2 image types that can be uploaded:</p><ul><li>Selfie - one RGB (colour) selfie image of the user</li><li>Liveness images (optional) - 8 colour images of the user’s face captured while the user was prepping to take the selfie image (it’s recommended you use either our <a href="/pages/7trgDBnA2Y6Sj759MMIc">mobile SDKs</a> or <a href="/pages/-Ma8qWQ8z6xQWoGSRWiK">Javascript SDK</a> to capture the liveness images)</li></ul><p><strong>The images can be added as base64 encoded strings or the image files themselves can be added to the zip and the filename specified in the info.json.</strong></p><p>{</p><p>"image\_type\_id": “varies based on image type and type of upload either base64 string or filename. Read more on <a href="/pages/-MaeazELMSJgL6ojO1Jg">image types</a> in the FAQs in documentation”,</p><p>"image": "",</p><p>"file\_name": "" }</p><p>Depending on the image\_type\_id one of the other parameters (image or file\_name) will be an empty string i.e. “”</p> |

**Info.json Example**

As explained 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 image files (if the image files themselves are uploaded).

*Example zip file and info.json when Images are Inline (i.e. Base64 Encoded Strings)*

![The zip file contains only the info.json file, the images are added inline in the info.json file as base64 encoded strings.](https://lh6.googleusercontent.com/DbYIJsvBl1fkf98m2Vs0XMqbHDW6gzRPVnr7E3W_cAaKr2C2Tj-0Z6RIabQVNysV_3KvyDmyS3gSf7-U0uAANyUPvxx_-g1ihnMEVILuiHoatsDVVa34ZtzP5D-qx9bfM7COcH3H)

{% hint style="info" %}
Note: `"entered":true` in ID info is required.
{% endhint %}

{% hint style="danger" %}
**Do not zip the containing folder.** The info.json file should be in the root of the zip file.
{% endhint %}

```json
{
  "package_information":
  {
    "apiVersion": {
      "buildNumber": 0,
      "majorVersion": 2,
      "minorVersion": 0
    }
  },
  "id_info":
  {
    "dob":"<dob in ID type specific format>",
    "country":"<country code e.g. KE>",
    "entered":true <job type 1> | false,
    "id_type":"smile ID type keyword e.g. NATIONAL_ID",
    "id_number":"The ID number e.g. 00000000",
    "last_name":"Joe",
    "first_name":"Leo",
    "middle_name":"Doe"
  },
  "images": [
    {
      <Selfie image>
      "image_type_id": 2,
      "image": "VBORw0KGgoAAAANSUhEUgAAArg---truncated base64 string",
      "file_name": ""
    },
    {
      <liveness images, repeat this json blob for all 8 colour images>
      "image_type_id": 6,
      "image": "iVBORw0KGgoAAAANSUhEUgAAAjoAAAFaCAYA---truncated base64 string",
      "file_name": ""
    }
  ]
}
```

*Example zip file and info.json when Images are uploaded as files*

![The zip contains info.json and the images as files](/files/3NqE3X6WO1KRrcPCAmM2)

{% hint style="danger" %}
**Do not zip the containing folder.** The info.json file and images should be in the root of the zip file.
{% endhint %}

```json
{
  "package_information":
  {
    "apiVersion": {
      "buildNumber": 0,
      "majorVersion": 2,
      "minorVersion": 0
    }
  },
  "id_info":
  {
    "dob":" <dob in ID type specific format>",
    "country":" <country code e.g. KE>",
    "entered":true <job type 1> | false,
    "id_type":"smile ID type keyword e.g. NATIONAL_ID",
    "id_number":"The ID number e.g. 00000000",
    "last_name":"Joe",
    "first_name":"Leo",
    "middle_name":"Doe"
  },
  "images": [
    {
      <Selfie image>
      "image_type_id": 0,
      "image": "",
      "file_name": "Selfie.jpeg"
    },
  {
      <liveness images, repeat this json blob for the other 8 colour images>
      "image_type_id": 4,
      "image": "",
      "file_name": "1.jpg"
    }
  ]
}
```

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

For each successful Biometric KYC job, you will get two different responses to your callback:

1. Actions response which details the actions that were carried out on the job
2. ID information response which contains the information of the user retrieved from the ID authority

{% hint style="info" %}
The size of the payload sent to your callback varies based on the size of image returned by the ID authority. We recommend your callback should accept payloads up to 1.5MB in size.
{% endhint %}

### Actions Response

<table data-header-hidden><thead><tr><th width="205">Name</th><th width="150">Type</th><th width="209">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>1</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>For a list of potential error codes see <a href="#result-codes-and-result-texts">here</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>List of all result text is listed <a href="#result-codes-and-result-texts">here</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_Compare</td><td>String</td><td>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</td><td><p>“Passed”</p><p>“Failed”</p><p>“Unable to Determine”</p><p>“Not Applicable”</p></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 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 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>Return_Personal_Info</td><td>String</td><td>Return user’s PII from ID authority</td><td><p>“Returned”</p><p>“Not Returned”</p><p>“Not Applicable”</p></td></tr><tr><td>Selfie_Provided</td><td>String</td><td>User provided a usable selfie</td><td></td></tr><tr><td>Selfie_To_ID_Authority_Compare</td><td>String</td><td>Compare user submitted selfie to government ID authority photo</td><td><p>“Completed”</p><p>“Under Review”</p><p>“ID Authority Photo Not Available”</p><p>“Not Applicable”</p></td></tr><tr><td>Selfie_To_ID_Card_Compare</td><td>String</td><td>Compare user submitted to user submitted ID card photo</td><td><p>“Completed”</p><p>“Under Review”</p><p>“Not Applicable”</p></td></tr><tr><td>Verify_ID_Number</td><td>String</td><td>Query ID number in the ID authority database</td><td><p>“Verified”</p><p>“Not Verified”</p><p>“Issuer Unavailable”</p><p>“Not Applicable”</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": "Passed",
    "Human_Review_Liveness_Check": "Passed",
    "Human_Review_Selfie_Check": "Not Applicable",
    "Human_Review_Update_Selfie": "Not Applicable",
    "Liveness_Check": "Not Applicable",
    "Register_Selfie": "Approved",
    "Return_Personal_Info": "Returned",
    "Selfie_Check": "Passed",
    "Selfie_Provided": "Passed",
    "Selfie_To_ID_Authority_Compare": "Completed",
    "Selfie_To_ID_Card_Compare": "Not Applicable",
    "Selfie_To_Registered_Selfie_Compare": "Not Applicable",
    "Update_Registered_Selfie_On_File": "Not Applicable",
    "Verify_ID_Number": "Verified"
  },
  "ConfidenceValue": "99",
  "ImageLinks": {
    "id_photo_image": "https://signed-url-to-image-file",
    "selfie_image": "https://signed-url-to-image-file"
  },
  "KYCReceipt": "https://signed-url-to-kyc-receipt-pdf-file",
  "PartnerParams": {
    "job_id": "20250124-1013-8831-b767-fcba3ab40ca1",
    "job_type": 1,
    "meta_data1": "custom value",
    "meta_data2": "custom value 2",
    "sandbox_result": "2",
    "user_id": "UserBioKYC-UgRvL"
  },
  "ResultCode": "1210",
  "ResultText": "Enroll User",
  "signature": "--signature--",
  "SmileJobID": "0000181776",
  "Source": "android 10.4.1",
  "timestamp": "2025-01-24T10:14:53.086Z"
}
```

{% hint style="warning" %}
The `ConfidenceValue` key has been deprecated. Please make decisions using the `ResultCode` and `ResultText` keys.
{% endhint %}

### ID Information Response

<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>Name</td><td>Type</td><td>Description</td><td>Return Values</td></tr><tr><td>Actions</td><td>object</td><td>A JSON object containing the details of the individual field comparisons</td><td></td></tr><tr><td>Actions.Return_Personal_Info</td><td>string</td><td>Indicates whether personal info from the ID authority was returned</td><td>"Returned"<br>"Not Returned"</td></tr><tr><td>Actions.Verify_ID_Number</td><td>string</td><td>The result of looking up the ID number in the ID authority database</td><td>"Verified"<br>"Not Verified"</td></tr><tr><td>Address</td><td>string</td><td><p>Address of ID owner</p><p>NOTE: this might not be the current address of the ID owner</p></td><td></td></tr><tr><td>Country</td><td>string</td><td>Country where the ID was issued as supplied by you</td><td></td></tr><tr><td>CountryOfBirth</td><td>string</td><td>Country of birth of the ID owner (when available)</td><td></td></tr><tr><td>DOB</td><td>string</td><td>Date of birth as retrieved from the ID authority database</td><td></td></tr><tr><td>DateOfDeath</td><td>string</td><td>Date of death of the ID owner (when available)</td><td></td></tr><tr><td>Document</td><td>string</td><td>Photo of ID card on file in the ID authority database (when applicable)</td><td></td></tr><tr><td>Email</td><td>string</td><td>Email address of the ID owner (when available)</td><td></td></tr><tr><td>ExpirationDate</td><td>string</td><td>Expiration date as retrieved from the ID authority database (when available)</td><td></td></tr><tr><td>FirstName</td><td>string</td><td>First name of the ID owner</td><td></td></tr><tr><td>FullName</td><td>string</td><td>Full name as retrieved from the ID authority database</td><td></td></tr><tr><td>Gender</td><td>string</td><td>Gender of ID owner</td><td></td></tr><tr><td>IDNumber</td><td>string</td><td>ID number you ran a query for</td><td></td></tr><tr><td>IDNumberPreviouslyRegistered</td><td>boolean</td><td><p>Boolean value that informs you if ID number has previously been used successfully to register a user.</p><p>Only available on <em>Biometric KYC</em> product.</p></td><td>true or false</td></tr><tr><td>IDStatus</td><td>string</td><td>Status of the ID owner in Smile ID checks (when available)</td><td></td></tr><tr><td>IDType</td><td>string</td><td>ID type as supplied by you</td><td></td></tr><tr><td>ImageLinks</td><td>object</td><td>Links to ID authority images (when available)</td><td></td></tr><tr><td>ImageLinks.id_photo_image</td><td>string</td><td>Signed URL to the ID photo image file (when available)</td><td></td></tr><tr><td>ImageLinks.selfie_image</td><td>string</td><td>Signed URL to the selfie image file (when available)</td><td></td></tr><tr><td>IssuanceDate</td><td>string</td><td>Issuance date as retrieved from the ID authority database</td><td></td></tr><tr><td>IsAlive</td><td>string</td><td>Indicates if the ID owner is alive (when available)</td><td></td></tr><tr><td>KYCReceipt</td><td>string</td><td>Link to download summary of job.<br><br>Read more about KYC receipts <a href="/pages/HQ0N5T1teUDOBtwTXJ0Q">here</a></td><td></td></tr><tr><td>LastName</td><td>string</td><td>Last name of the ID owner</td><td></td></tr><tr><td>LocalAreaOfOrigin</td><td>string</td><td>Local area of origin of the ID owner (when available)</td><td></td></tr><tr><td>Nationality</td><td>string</td><td>Nationality of the ID owner (when available)</td><td></td></tr><tr><td>Occupation</td><td>string</td><td>Occupation of the ID owner (when available)</td><td></td></tr><tr><td>OtherNames</td><td>string</td><td><p>Other names of the ID owner (also known as middle name)</p><p>(when available)</p></td><td></td></tr><tr><td>PartnerParams</td><td>object</td><td>Partner-defined parameters echoed back in the response</td><td></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>number</td><td>The type of job you performed</td><td>1</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>PhoneNumber</td><td>string</td><td>Phone number as retrieved from the ID authority database</td><td></td></tr><tr><td>PhoneNumber2</td><td>string</td><td>Second phone number of ID owner (when available)</td><td></td></tr><tr><td>Photo</td><td>string</td><td>Top level key - photo as retrieved from the ID authority database in base64 image</td><td></td></tr><tr><td>PlaceOfBirth</td><td>string</td><td>Place of birth of the ID owner (when available)</td><td></td></tr><tr><td>PlaceOfIssuance</td><td>string</td><td>Place of issuance of the ID (when available)</td><td></td></tr><tr><td>RegionOfOrigin</td><td>string</td><td>Region of origin of the ID owner (when available)</td><td></td></tr><tr><td>ResultCode</td><td>string</td><td>Numeric value of the job outcome.</td><td>For a list of potential result codes see <a href="#result-codes-and-result-texts">here</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 in our <a href="#result-codes-and-result-texts">documentation</a>.</td></tr><tr><td>SecondaryIDNumber</td><td>string</td><td>Secondary ID number for the ID owner (when available)</td><td></td></tr><tr><td>signature</td><td>string</td><td>The outgoing signature, you can use this to verify that the response is from Smile ID</td><td></td></tr><tr><td>SmileJobID</td><td>string</td><td>The Smile internal reference number for the job. Please include this when contacting support on a job.</td><td></td></tr><tr><td>StructuredAddress</td><td>object</td><td>Structured address details (when available)</td><td></td></tr><tr><td>StructuredAddress.AddressLine1</td><td>string</td><td>Address line 1 (when available)</td><td></td></tr><tr><td>StructuredAddress.AddressLine2</td><td>string</td><td>Address line 2 (when available)</td><td></td></tr><tr><td>StructuredAddress.Country</td><td>string</td><td>Country for the structured address (when available)</td><td></td></tr><tr><td>StructuredAddress.Locality</td><td>string</td><td>Locality for the structured address (when available)</td><td></td></tr><tr><td>StructuredAddress.MainAdminArea</td><td>string</td><td>Main administrative area for the structured address (when available)</td><td></td></tr><tr><td>StructuredAddress.PostalCode</td><td>string</td><td>Postal code for the structured address (when available)</td><td></td></tr><tr><td>StructuredAddress.SubAdminArea</td><td>string</td><td>Sub administrative area for the structured address (when available)</td><td></td></tr><tr><td>timestamp</td><td>string</td><td>The outgoing timestamp in ISO date/time format, use this to calculate the outgoing Signature</td><td></td></tr><tr><td>Title</td><td>string</td><td>Title of the ID owner (when available)</td><td></td></tr><tr><td>UserIDsOfPreviousRegistrants</td><td>array</td><td><p>Registered User IDs that have previously used the ID info you just queried.</p><p>Only available on <em>Enhanced KYC + SmartSelfie™</em> product.</p></td><td>["12134","23456"]</td></tr></tbody></table>

#### Example JSON Response

```json
{
    "Actions": {
        "Return_Personal_Info": "Returned",
        "Verify_ID_Number": "Verified"
    },
    "Address": "NO 1 Smile Street, general area, full address",
    "Country": "NG",
    "CountryOfBirth": "",
    "DOB": "YYYY-MM-DD",
    "DateOfDeath": "",
    "Document": "",
    "Email": "user@email.com",
    "ExpirationDate": "",
    "FirstName": "Joe",
    "FullName": "Joe Leo Doe",
    "Gender": "f",
    "IDNumber": "00000000000",
    "IDNumberPreviouslyRegistered": true,
    "IDStatus": "NOT_WATCHLISTED",
    "IDType": "BVN",
    "ImageLinks": {
        "id_photo_image": "https://signed-url-to-image-file",
        "selfie_image": "https://signed-url-to-image-file"
    },
    "IssuanceDate": "",
    "KYCReceipt": "https://signed-url-to-kyc-receipt-pdf-file",
    "IsAlive": "",
    "LastName": "Doe",
    "LocalAreaOfOrigin": "",
    "Nationality": "",
    "Occupation": "",
    "OtherNames": "Leo",
    "PartnerParams": {
        "job_id": "job-b38d23c8855c",
        "job_type": 1,
        "user_id": "user-6f11d47621f1"
    },
    "PhoneNumber": "08012345678",
    "PhoneNumber2": "",
    "Photo": "/9j/4AAQSkZJRgABAgAAAQABAAD",
    "PlaceOfBirth": "",
    "PlaceOfIssuance": "057",
    "RegionOfOrigin": "Ebonyi State",
    "ResultCode": "1012",
    "ResultText": "ID Number Validated",
    "SecondaryIDNumber": "",
    "signature": "VYvClVV20D77vULLD3LzNI=",
    "SmileJobID": "100000001",
    "StructuredAddress": {
        "AddressLine1": "NO 1 Smile Street, general area, full address",
        "AddressLine2": "",
        "Country": "NG",
        "Locality": "",
        "MainAdminArea": "",
        "PostalCode": "",
        "SubAdminArea": ""
    },
    "timestamp": "2026-03-12T11:18:47.371Z",
    "Title": "Mr",
    "UserIDsOfPreviousRegistrants": [
        "user-6f11d47621"
    ]
}
```

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

| Code              | Text                                                                                                                                 | Description                                                                                                                                                                                                                 | Category |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| 0001              | Data Invalid                                                                                                                         | Uploaded zip is corrupted                                                                                                                                                                                                   | Rejected |
| 0001              | ID Authority image not available                                                                                                     | There was no photo returned by the id authority for the submitted ID number                                                                                                                                                 | Rejected |
| 0001              | ID Card image unusable                                                                                                               | The submitted ID card image is corrupted or was not included in zip                                                                                                                                                         | Rejected |
| 0001              | System Error                                                                                                                         | A system error occurred                                                                                                                                                                                                     | 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. [Please see how to resolve this here.](/further-reading/troubleshooting/troubleshooting-error-2204-and-2205-youre-not-authorized-to-do-that.md#signature-miscalculation) | -        |
| 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](#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](#request-values) for this product.                                                                                                         | -        |
| 2205              | Error - You are not authorized to do that. \*                                                                                        | An invalid signature was used to sign the request. [Please see how to resolve this here.](/further-reading/troubleshooting/troubleshooting-error-2204-and-2205-youre-not-authorized-to-do-that.md#signature-miscalculation) | -        |
| 2220              | Error - Production is not enabled for this account. Please complete your [KYC with Smile ID.](/getting-started/complete-your-kyc.md) | 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](/further-reading/troubleshooting/troubleshooting-error-2204-and-2205-youre-not-authorized-to-do-that.md)\
\*\* - set Job Type to 1

### Product Specific Result Codes and Texts (Action Callback)

| Code | Text                                                                     | Description                                                                                                                                                                            | Category                                                             |
| ---- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| 1013 | Invalid ID                                                               | The ID info provided 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](/supported-id-types/for-individuals-kyc/backed-by-id-authority/id-number-regex.md) samples as a guide.        | Rejected                                                             |
| 1015 | Error - Queried Database Unavailable                                     | The ID authority is unavailable.                                                                                                                                                       | Re-run the job when ID authority is back online                      |
| 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 | <p>Enroll User</p><p>Machine Judgement - PASS</p>                        | Images matched and no spoof detected on the selfie.                                                                                                                                    | Approved                                                             |
| 0811 | <p>Failed Enroll</p><p>Machine Judgement - FAIL - Compare Rejected</p>   | Images did not match and job was therefore rejected.                                                                                                                                   | Rejected                                                             |
| 0812 | Machine Judgement - Pure Provisional                                     | Waiting on document reviewer's decision.                                                                                                                                               | Provisionally Approved                                               |
| 0813 | <p>Failed Enroll</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                                                             |
| 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.                                  | Suspected for spoof and sent to document reviewer for final decision |
| 0815 | Machine Judgement - Provisional - Compare Unsure                         | The machine is not sure if both images match, so a document reviewer will compare.                                                                                                     | Provisionally Approved                                               |
| 1210 | <p>Enroll User</p><p>Human Judgement - PASS</p>                          | The human reviewer marked that both images are of the same person and no spoof was detected.                                                                                           | Approved                                                             |
| 1211 | <p>Failed Enroll</p><p>Human Judgement - FAIL - Human Compare Failed</p> | The human reviewer marked that both images are different persons.                                                                                                                      | Rejected                                                             |
| 1212 | <p>Failed Enroll</p><p>Human Judgement - Spoof Detected</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                                                             |
| 1213 | Human Judgement - Provisional - Liveliness Unsure                        | The human reviewer is not sure if there is a possible fraud attempt on the Selfie.                                                                                                     | Inconclusive                                                         |
| 0908 | Error - Issuer not available                                             | The ID authority is unavailable.                                                                                                                                                       | Re-run the job when ID authority is back online                      |
| 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.                                                                                                                             | Re-run the job with a different `user_id`                            |

### Product Specific Result Codes and Texts (ID Response Callback)

| Code |                                         | Description                                                                                                                                                                     | Category                                        |
| ---- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| 1012 | ID Verification Success                 | The ID info is valid and was found in the ID authority database.                                                                                                                | ID info is valid                                |
| 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](/supported-id-types/for-individuals-kyc/backed-by-id-authority/id-number-regex.md) samples as a guide. | Rejected                                        |
| 1015 | Error - Queried Database Unavailable \* | The ID authority is unavailable.                                                                                                                                                | Re-run the job when ID authority is back online |

## Spotting Repeat ID Number Usage

We recognise that there are legitimate reasons why a user may need multiple accounts using the same credentials for KYC. As a result, we allow your users to register a selfie with an ID Number multiple times.

However, we track if an ID has previously been used to run a successful Biometric KYC and return the `user_id`s of all those users. There are two methods to get the list of `user_id`(s) who have previously used the ID:

### ID Response sent to your Callback

![ID response sent to callback](/files/zG6suTAYhw4qYftudF3S)

If the ID number submitted with the job has been previously used, we return `true` in the `IDNumberPreviouslyRegistered` key and all registered `user_id`s are listed in the array `UserIDsOfPreviousRegistrants` as shown above. Both the `IDNumberPreviouslyRegistered` and `UserIDsOfPreviousRegistrants` are keys in the ID response sent to the callback you specified when running the job.

### Polling [Job Status](/further-reading/job-status.md)

![Job status response](/files/NefJWLxC0qx0XQFt26au)

If the ID number submitted with the job has been previously used, we return `true` in the `IDNumberPreviouslyRegistered` key and all registered `user_id`s are listed in the array `UserIDsOfPreviousRegistrants` as shown above. Both the `IDNumberPreviouslyRegistered` and `UserIDsOfPreviousRegistrants` are sub-keys in the `history` object of the job status response.


---

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