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

# Basic KYC

{% hint style="info" %}
Running Basic KYC in Uganda? Learn more [here](/supported-id-types/for-individuals-kyc/backed-by-id-authority/supported-countries/uganda/national-id-without-photo/basic-kyc-in-uganda.md).
{% endhint %}

## Overview

The Basic KYC API enables verification of an individual's identity information using their personal details and the ID number from one of our supported [ID Types](/supported-id-types/for-individuals-kyc/backed-by-id-authority.md). This API returns a result of no match, partial match, or exact match, along with detailed data on the matching outcomes for specific fields.

## Integration Options

Basic KYC is currently available only through the [REST API](/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 if the ID authority is unavailable. For high-volume applications, the Asynchronous API is required. If you are using the Asynchronous API, you must include a [callback endpoint](/further-reading/faqs/how-do-i-setup-a-callback.md) in your request to receive the response. The URLs for the endpoints are:

**Asynchronous:**

| Environment | URL                                                   |
| ----------- | ----------------------------------------------------- |
| Sandbox     | <https://testapi.smileidentity.com/v2/verify\\_async> |
| Production  | <https://api.smileidentity.com/v2/verify\\_async>     |

**Synchronous:**

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

## Request Values

The Basic KYC API requires the following input parameters in a JSON body object submitted to the endpoint:

**Request Type:** POST

<table><thead><tr><th width="230">Name</th><th width="104">Type</th><th width="150">Required</th><th>Description</th></tr></thead><tbody><tr><td>source_sdk</td><td>string</td><td>Yes</td><td>The integration option you are using. For the 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. This can be any value (including your own).</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>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>Country code. Link to country codes <a href="/pages/-Ma8myUwif8S8KMRDnYS#know-your-customer-kyc">here</a>.</td></tr><tr><td>id_type</td><td>string</td><td>Yes</td><td>Supported ID type. <a href="/pages/-Ma8myUwif8S8KMRDnYS">More information</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 (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="https://docs.smileidentity.com/results/callbacks">here</a>.</td></tr><tr><td>first_name</td><td>string</td><td>Yes</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>Yes</td><td>Last name.</td></tr><tr><td>dob</td><td>string</td><td>No</td><td><p>Date of birth (YYYY-MM-DD).<br></p><p><strong>Note:</strong> For the Nigerian Voter ID, only the birth year should be entered in the format <code>YYYY</code>.</p></td></tr><tr><td>gender</td><td>string</td><td>No</td><td>Gender (M, F).</td></tr><tr><td>phone_number</td><td>string</td><td>No</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 listed 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_id</td><td>string</td><td>Yes</td><td>A value generated by you to 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 to 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": "Joe",
  "gender": "M",
  "id_number": "00000000000",
  "id_type": "NIN",
  "last_name": "Leo",
  "middle_name": "Doe",
  "partner_id": "023",
  "partner_params": {
    "job_id": "3ba0e15e-1a56-4799-a94d-b0e084f50256",
    "user_id": "4cb0f26-2b567-5800-b05e-c0f095g6036"
  },
  "phone_number": "0123456789",
  "signature": "...",
  "source_sdk_version": "2.0.0",
  "source_sdk": "rest_api",
  "timestamp": "2024-04-13T17:57:00.614879"
}
```

## Return Values

The Basic 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><thead><tr><th>Name</th><th width="150">Type</th><th>Description</th><th>Return Values</th></tr></thead><tbody><tr><td>SmileJobID</td><td>string</td><td>The Smile internal reference number for the job.</td><td></td></tr><tr><td>PartnerParams</td><td>object</td><td>The contents of the partner_params object from the request.</td><td></td></tr><tr><td>ResultText</td><td>string</td><td>Textual value of the match outcome.</td><td>“Partial Match”, “Exact Match”, “No Match”</td></tr><tr><td>ResultCode</td><td>string</td><td>Numeric value of the match.</td><td>1020 = Exact Match, 1021 = Partial Match, 1022 = No Match. Find a list of potential error codes below.</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>Return_Personal_Info</td><td>string</td><td>Confirms if the personal information retrieved from the ID authority was sent to you.</td><td>“Not Applicable”</td></tr><tr><td>Verify_ID_Number</td><td>string</td><td>The result of looking up the ID number in the ID authority database.</td><td>“Verified”, “Not Verified”, “Not Done”, “Issuer Unavailable”</td></tr><tr><td>Names</td><td>string</td><td>Result of comparing names supplied by the user with the names returned by the ID authority.</td><td>“Exact Match”, “Partial Match”, “Transposed”, “No Match”</td></tr><tr><td>DOB</td><td>string</td><td>Result of comparing the date of birth supplied by the user with the date of birth returned by the ID authority.</td><td>“Exact Match”, “Partial Match”, “Transposed”, “No Match”</td></tr><tr><td>Gender</td><td>string</td><td>Result of comparing gender supplied by the user with the gender returned by the ID authority.</td><td>“Exact Match”, “No Match”, “Not Provided”</td></tr><tr><td>Phone_Number</td><td>string</td><td>Result of comparing the phone number supplied by the user with the phone number returned by the ID authority.</td><td>“Exact Match”, “No Match”, “Not Provided”</td></tr><tr><td>ID_Verification</td><td>string</td><td>Same as ResultText.</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>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></tbody></table>

### Example JSON Response

The response you receive varies depending on whether you use the asynchronous or synchronous endpoint.

**For the Asynchronous Endpoint:**

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

**For the Synchronous Endpoint** (this response is also sent to the callback of the asynchronous endpoint):

```json
{
  "SmileJobID": "0000055474",
  "PartnerParams": {
    "job_id": "3ba0e15e-1a56-4799-a94d-b0e084f50256",
    "job_type": 5,
    "user_id": "4cb0f26-2b567-5800-b05e-c0f095g6036"
  },
  "ResultText": "Exact Match",
  "ResultCode": "1020",
  "Actions": {
    "DOB": "Exact Match",
    "Gender": "Exact Match",
    "ID_Verification": "Exact Match",
    "Names": "Exact Match",
    "Phone_Number": "Exact Match",
    "Return_Personal_Info": "Not Applicable",
    "Verify_ID_Number": "Verified"
  },
  "Source": "ID Verification",
  "signature": "...",
  "timestamp": "2024-04-13T17:57:00.614879"
}
```

## **Evaluating the Results**

You can choose to use the ResultCode and ResultText to make a verification decision or you can make a more granular decision based on the values from the individual fields located in the actions object. If all the underlying fields are an exact match the overall result is an exact match. If all the underlying fields are any mixture of exact, partial match, or transposed then the overall result is a partial match. If any of the fields are no match then the entire result is no match. Here is an explanation of the matching rules:

| Exact Match   | The values are a case-insensitive exact match                                                                                                                                                                                                                                                                                                        |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Partial Match | For name values it is a partial match if the values are a [levenshtein distance](https://en.wikipedia.org/wiki/Levenshtein_distance) of <= 2 apart. For date of birth it is a partial match if any single component (Day, Month, Year) is within 1 digit of the returned value. If more than one component of date birth is off then it is no match. |
| Transposed    | Two elements are transposed. For example first name and last name or month of birth and date of birth                                                                                                                                                                                                                                                |
| Not Provided  | An optional field was not provided with the request                                                                                                                                                                                                                                                                                                  |
| No Match      | All other cases                                                                                                                                                                                                                                                                                                                                      |

## Result Codes and Result Texts

Result codes details what the current (or final) result of a job is. Basic KYC Result Codes 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 |
| ---- | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| 0001 | Data Invalid                                                                                                                         |                                                                                                                                                | Rejected |
| 2405 | Error - "You are not authorized to do that" \*                                                                                       | An invalid signature was used to sign the request.                                                                                             | -        |
| 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".                                                                   | -        |
| 2413 | Error - valid id\_type is required                                                                                                   | An invalid or unsupported country/id\_type pair was used in 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)\
\&#xNAN;**\*\* - set Job Type to "5"**

Product Specific Result Codes and Texts

| Code | Text                                 | Description                                                                                                                                                                     | Category |
| ---- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| 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.                                                                                             | -        |
| 1020 | Exact Match                          | The user submitted details exactly match the ID info in the ID authority database.                                                                                              | Approved |
| 1021 | Partial Match                        | At least one of the user submitted details partially/exactly match the ID info in the ID authority database.                                                                    | Approved |
| 1022 | No Match                             | None of the user submitted details partially/exactly match the ID info in the ID authority database.                                                                            | 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/basic-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.