> 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/identity-lookup.md).

# Enhanced KYC

{% hint style="info" %}
**NOTE**

Only available to licensed organisations.\
Please contact <compliance@usesmileid.com> if you need access to this product.
{% endhint %}

## Overview

The Enhanced KYC API allows you to query the Identity Information for an individual using their ID number from one of our supported [ID Types](/supported-id-types/for-individuals-kyc/backed-by-id-authority.md). This API will return the personal information of the individual found in the database of the ID authority.

## Integration Options

Only available using [Mobile](/integration-options/mobile.md), [Server-to-Server](/integration-options/server-to-server.md) and [Rest APIs](/integration-options/rest-api.md).

## Asynchronous vs Synchronous

This API is available as both an Asynchronous API (recommended) which guarantees an eventual response regardless of ID authority availability and as a Synchronous API to be used in real time environments such as mobile applications which does not guarantee a response in the case that an ID authority is unavailable. For high volume applications the Asynchronous API is required. If you are using the Asynchronous API you must have a [callback endpoint](/further-reading/faqs/how-do-i-setup-a-callback.md) in your request where the response will be delivered. The urls for the endpoints are:

{% 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 %}

**Asynchronous:**

| Environment | URL                                                              |
| ----------- | ---------------------------------------------------------------- |
| Sandbox:    | <https://testapi.smileidentity.com/v1/async\\_id\\_verification> |
| Production: | <https://api.smileidentity.com/v1/async\\_id\\_verification>     |

**Synchronous:**

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

## **Request Values**

The Enhanced KYC API has the following input parameters which should be contained in a JSON body object submitted to the endpoint

**Request Type:** Post

<table data-header-hidden><thead><tr><th>Name</th><th width="150">Type</th><th width="150">Required</th><th>Description</th></tr></thead><tbody><tr><td>Name</td><td>Type</td><td>Required</td><td>Description</td></tr><tr><td>partner_id</td><td>string</td><td>Yes</td><td>A unique number assigned by Smile ID to your account. Can be found with your API key <a href="https://portal.usesmileid.com/api-key">here</a></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>The outgoing signature to authenticate the request from you to Smile ID</td></tr><tr><td>timestamp</td><td>string</td><td>Yes</td><td>The timestamp used to calculate the signature in ISO date/time format</td></tr><tr><td>country</td><td>string</td><td>Yes</td><td>The country where the ID was issued. Link to country codes <a href="/pages/-Ma8myUwif8S8KMRDnYS">here</a></td></tr><tr><td>id_type</td><td>string</td><td>Yes</td><td>The type of ID you want to look up. <a href="/pages/-Ma8myUwif8S8KMRDnYS">Supported ID type</a></td></tr><tr><td>id_number</td><td>string</td><td>Yes</td><td>ID number, you can enforce ID number format using our regex examples <a href="/pages/-MaHwx30okMx0ROKTbqh">here</a></td></tr><tr><td>callback_url</td><td>string</td><td>Yes for Async</td><td>Your callback url, results of jobs will be sent to the specified url. You can read more about callback urls <a href="/pages/-MaSsBxi_CDOXZEXrdyn">here</a></td></tr><tr><td>first_name</td><td>string</td><td><a href="/pages/-Ma8myUwif8S8KMRDnYS">Varies by ID Type</a></td><td>First Name</td></tr><tr><td>middle_name</td><td>string</td><td>No</td><td>Middle Name</td></tr><tr><td>last_name</td><td>string</td><td><a href="/pages/-Ma8myUwif8S8KMRDnYS">Varies by ID Type</a></td><td>Last Name</td></tr><tr><td>dob</td><td>string</td><td><a href="/pages/-Ma8myUwif8S8KMRDnYS">Varies by ID Type</a></td><td>Date of Birth</td></tr><tr><td>phone_number</td><td>string</td><td><a href="/pages/-Ma8myUwif8S8KMRDnYS">Varies by ID Type</a></td><td>Phone Number</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 5.</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></tbody></table>

### Example JSON Body

```json
{
  "callback_url": "example.webhook.com",
  "country": "NG",
  "dob": "2000-09-20",
  "first_name": "Leo",
  "gender": "M",
  "id_number": "ABC000000000",
  "id_type": "DRIVERS_LICENSE",
  "last_name": "Joe",
  "middle_name": "Doe",
  "partner_id": "023",
  "partner_params": {
    "job_id": "3ba0e15e-1a56-4799-a94d-b0e084f50256",
    "job_type": 5,
    "user_id": "4cb0f26-2b567-5800-b05e-c0f095g6036"
  },
  "phone_number": "1234567890",
  "signature": "...",
  "source_sdk": "rest_api",
  "source_sdk_version": "1.0.0",
  "timestamp": "2021-08-12T17:57:00.614"
}
```

## Return Values

The Enhanced KYC API returns a set of top level values as well as a detailed set of actions that can be used for a more granular evaluation of the individual fields.

<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>This key confirms if we sent the personal information retrieved from the ID authority sent to you</td><td><p>"Returned"</p><p>"Not Returned"</p><p>"Not Applicable"</p></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 is returned in this key</td><td><p>"Verified"</p><p>"Not Verified"</p><p>"Not Done"</p><p>"Issuer Unavailable"</p></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 where the ID owner was born</td><td></td></tr><tr><td>DateOfDeath</td><td>string</td><td>Date of death of the ID owner if <code>IsAlive</code> is true</td><td></td></tr><tr><td>DOB</td><td>string</td><td>Date of birth as retrieved from the ID authority database. It will be in the format <code>"YYYY-MM-DD"</code></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 if available</td><td></td></tr><tr><td>ExpirationDate</td><td>string</td><td>Expiration date as retrieved from the ID authority database</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. Typically a concatenation of all available names</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>IDStatus</td><td>string</td><td>The status of the ID</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>An object containing links to the ID photo image if available. <strong>Returned on the asynchronous callback response.</strong> This is not returned when there is no image link.</td><td></td></tr><tr><td>ImageLinks.id_photo_image</td><td>string</td><td>Signed url to ID photo image. <strong>Returned on the asynchronous callback response.</strong> This is not returned when there is no image.</td><td></td></tr><tr><td>IsAlive</td><td>string</td><td>If the ID owner is alive or not</td><td></td></tr><tr><td>IsFinalResult</td><td>string</td><td>Indicates if this response is a final result</td><td><p>"true"</p><p>"false"</p></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>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</td><td></td></tr><tr><td>Nationality</td><td>string</td><td>Nationality of the ID owner</td><td></td></tr><tr><td>Occupation</td><td>string</td><td>Occupation of the ID owner</td><td></td></tr><tr><td>OtherNames</td><td>string</td><td>Other names of the ID owner</td><td></td></tr><tr><td>PartnerParams</td><td>object</td><td>Object containing the parameters provided by you.</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>5</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>Top level key - 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 within the country of birth of the ID owner</td><td></td></tr><tr><td>PlaceOfIssuance</td><td>string</td><td>Place of issuance within the country of issuance of the ID owner</td><td></td></tr><tr><td>RegionOfOrigin</td><td>string</td><td>Region of origin of the ID owner</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>Full list of result text in our <a href="#result-codes-and-result-texts">documentation</a>.</td></tr><tr><td>ResultType</td><td>string</td><td>The type of result returned</td><td></td></tr><tr><td>SecondaryIDNumber</td><td>string</td><td>Another ID number that is tied to another ID type</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>Source</td><td>string</td><td>The source of the initial request</td><td></td></tr><tr><td>StructuredAddress</td><td>object</td><td>Object containing a structured breakdown of address fields.</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>success</td><td>boolean</td><td>Immediate acknowledgement returned by the asynchronous endpoint (not the callback result payload)</td><td><p>true</p><p>false</p></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>The title for addressing ID owner</td><td></td></tr></tbody></table>

### **Example JSON Response**

Depending on the endpoint you hit (asynchronous or synchronous) the immediate response you get is different.

**For the Asynchronous Endpoint**

```json
{
  "success": true
}
```

{% tabs %}
{% tab title="Synchronous Response (success)" %}

```json
{
    "Actions": {
        "Return_Personal_Info": "Returned",
        "Verify_ID_Number": "Verified"
    },
    "Address": "NO 1 Smile Street, general area, full address",
    "Country": "NG",
    "CountryOfBirth": "",
    "DateOfDeath": "",
    "DOB": "YYYY-MM-DD",
    "Document": "",
    "Email": "user@email.com",
    "ExpirationDate": "",
    "FirstName": "Joe",
    "FullName": "Joe Leo Doe",
    "Gender": "f",
    "IDNumber": "00000000000",
    "IDStatus": "",
    "IDType": "NIN_V2",
    "IsAlive": "",
    "IsFinalResult": "true",
    "IssuanceDate": "",
    "LastName": "Doe",
    "LocalAreaOfOrigin": "",
    "Nationality": "",
    "Occupation": "",
    "OtherNames": "Leo",
    "PartnerParams": {
        "job_id": "job-b38d23c8855c",
        "job_type": 5,
        "user_id": "user-6f11d47621f1"
    },
    "PhoneNumber": "08012345678",
    "PhoneNumber2": "",
    "Photo": "/9j/2wBDAAsICAoIBws",
    "PlaceOfBirth": "",
    "PlaceOfIssuance": "",
    "RegionOfOrigin": "",
    "ResultCode": "1012",
    "ResultText": "ID Number Validated",
    "ResultType": "ID Verification",
    "SecondaryIDNumber": "",
    "signature": "VYvClVV20D77vULLD3LzNI=",
    "SmileJobID": "100000001",
    "Source": "ID API",
    "StructuredAddress": {
        "AddressLine1": "NO 1 Smile Street, general area, full address",
        "AddressLine2": "",
        "Country": "NG",
        "Locality": "",
        "MainAdminArea": "",
        "PostalCode": "",
        "SubAdminArea": ""
    },
    "timestamp": "2026-02-08T18:04:22.384Z",
    "Title": ""
}
```

{% endtab %}

{% tab title="Asynchronous Response (success)" %}

```json
{
    "Actions": {
        "Return_Personal_Info": "Returned",
        "Verify_ID_Number": "Verified"
    },
    "Address": "NO 1 Smile Street, general area, full address",
    "Country": "NG",
    "CountryOfBirth": "",
    "DateOfDeath": "",
    "DOB": "YYYY-MM-DD",
    "Document": "",
    "Email": "user@email.com",
    "ExpirationDate": "",
    "FirstName": "Joe",
    "FullName": "Joe Leo Doe",
    "Gender": "f",
    "IDNumber": "00000000000",
    "IDStatus": "",
    "IDType": "NIN_V2",
    "ImageLinks": {
        "id_photo_image": "https://signed-url"
    },
    "IsAlive": "",
    "IsFinalResult": "true",
    "IssuanceDate": "",
    "LastName": "Doe",
    "LocalAreaOfOrigin": "",
    "Nationality": "",
    "Occupation": "",
    "OtherNames": "Leo",
    "PartnerParams": {
        "job_id": "job-b38d23c8855c",
        "job_type": 5,
        "user_id": "user-6f11d47621f1"
    },
    "PhoneNumber": "08012345678",
    "PhoneNumber2": "",
    "Photo": "/9j/2wBDAAsICAoIBws",
    "PlaceOfBirth": "",
    "PlaceOfIssuance": "",
    "RegionOfOrigin": "",
    "ResultCode": "1012",
    "ResultText": "ID Number Validated",
    "ResultType": "ID Verification",
    "SecondaryIDNumber": "",
    "signature": "VYvClVV20D77vULLD3LzNI=",
    "SmileJobID": "100000001",
    "Source": "ID API",
    "StructuredAddress": {
        "AddressLine1": "NO 1 Smile Street, general area, full address",
        "AddressLine2": "",
        "Country": "NG",
        "Locality": "",
        "MainAdminArea": "",
        "PostalCode": "",
        "SubAdminArea": ""
    },
    "timestamp": "2026-02-08T18:04:22.384Z",
    "Title": ""
}
```

{% endtab %}
{% endtabs %}

## **Evaluating the Results**

The Enhanced KYC product returns the personal information of users stored in the ID authority database. Each ID authority stores these personal information with different keys causing discrepancies in names of keys containing similar information. For the identity lookup response, we have filtered and standardised the personal information returned to [top-level keys](/further-reading/faqs/what-are-top-level-keys.md) to simplify the use of our JSON response across all our supported ID types.

## Result Codes and Result Texts

Result codes details what the current (or final) result of a job is. Result Codes for all Enhanced KYC jobs fall into one of two categories:

1. **Approved (or Pass)**\
   This means that all applicable Actions passed and the overall job was approved.
2. **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 |
| ---- | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| 2405 | Error - "You are not authorized to do that" \*                                                                                       | An invalid signature was used to sign the request.                                                                                             | -        |
| 2203 | Error - Invalid JSON                                                                                                                 | The json request body is not properly structured. Ensure all keys are present and properly named and in lower case.                            | -        |
| 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.                                                                                             | -        |
| 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 5.                                                                     | -        |

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

### Product Specific Result Codes and Texts

| Code | Text                                          | Description                                                                                                                                                                     | Category |
| ---- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| 1012 | Valid ID                                      |                                                                                                                                                                                 | Approved |
| 1013 | Invalid ID                                    | The ID info was not found in the ID authority database.                                                                                                                         | Rejected |
| 1014 | Error - 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. | -        |
| 1015 | Error - Queried Database Unavailable          | The ID authority is unavailable.                                                                                                                                                | -        |
| 1016 | Error - Need to Activate Product              | You do not have access to the ID Type. Please contact support for more information.                                                                                             | -        |
| 2211 | (Mobile SDK Only) ID Validation Failed        |                                                                                                                                                                                 | Rejected |
| 2212 | (Mobile SDK Only) Error - HTTP Request Failed |                                                                                                                                                                                 | -        |


---

# 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/identity-lookup.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.