> 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/phone-number-verification.md).

# Phone Number Verification

## Overview

The **Phone Number Verification** product is a low-friction solution designed to verify customer identities using their phone numbers. This product is especially beneficial for businesses targeting the unbanked population or those needing to comply with basic KYC regulations. The service is currently available in Ghana, South Africa, Tanzania, and Uganda covering over 330 million phone numbers across these regions.

## Integration Options

Only available via the [REST APIs](/integration-options/rest-api.md). There are two endpoints available: synchronous and asynchronous, but **we strongly recommend using the asynchronous endpoint** for most use cases due to its efficiency and ability to handle network delays better.

## Supported Countries

<table data-full-width="true"><thead><tr><th>Country</th><th>Phone Number Regex</th><th>Match Fields</th></tr></thead><tbody><tr><td>Ghana</td><td><code>/^[0-9]{10}$/</code></td><td>First Name, Other Name, Last Name</td></tr><tr><td>South Africa</td><td><code>/^[0-9]{10}$/</code></td><td>First Name, Other Name, Last Name, ID Number</td></tr><tr><td>Tanzania</td><td><code>/^[0-9]{12}$/</code></td><td>First Name, Other Name, Last Name</td></tr><tr><td>Uganda</td><td><code>/^[0-9]{10}$/</code></td><td>First Name, Other Name, Last Name</td></tr></tbody></table>

## Testing the Product in Sandbox

You can evaluate the Phone Number Verification product in Sandbox by utilizing the test data provided below:

<table data-full-width="true"><thead><tr><th width="117">Country</th><th width="157">Test Phone Number</th><th>Test Last Name</th><th>Test First Name</th><th>Test Other Name</th><th>Test ID Number</th></tr></thead><tbody><tr><td>Ghana</td><td><code>00000000000</code></td><td>Leo</td><td>Joe</td><td>Doe</td><td>N/A</td></tr><tr><td>South Africa</td><td><code>0000000000</code></td><td>Leo</td><td>Joe</td><td>Doe</td><td><code>0000000000000</code></td></tr><tr><td>Tanzania</td><td><code>000000000000</code></td><td>Leo</td><td>Joe</td><td>Doe</td><td>N/A</td></tr><tr><td>Uganda</td><td><code>0000000000</code></td><td>Leo</td><td>Joe</td><td>Doe</td><td>N/A</td></tr></tbody></table>

{% hint style="success" %}
One of the following operators is required for the Ghana Phone Number verification: `MTN`, `VODAFONE`, or `AIRTELTIGO`

e.g "operator": "MTN"
{% endhint %}

### How to Use the Test Data

There are four simulated Results to test your integration:

<table data-full-width="true"><thead><tr><th>Final Digit</th><th>Simulated Result</th><th>Code</th></tr></thead><tbody><tr><td>0 e.g. <code>0000000000</code></td><td>Varies based on <code>match_fields</code></td><td>Varies based on <code>match_fields</code></td></tr><tr><td>1 e.g<code>0000000001</code></td><td>Failure, no record found</td><td><code>1023</code></td></tr><tr><td>2 e.g. <code>0000000002</code></td><td>Invalid phone number format</td><td><code>2413</code></td></tr><tr><td>3 e.g. <code>0000000003</code></td><td>Database unavailable/unknown network issue</td><td><code>1015</code></td></tr></tbody></table>

## Endpoints

### Asynchronous vs. Synchronous Endpoints

{% tabs %}
{% tab title="Asynchronous Endpoint" %}

* **Endpoint:** `/v2/async-verify-phone`
* **Method:** POST
* **Description:** This endpoint allows you to verify a phone number asynchronously. The recommended approach for most integrations, it enables better handling of requests and is less prone to network-related issues.
  {% endtab %}

{% tab title="Synchronous Endpoint" %}

* **Endpoint:** `/v2/verify-phone-number`
* **Method:** POST
* **Description:** This endpoint allows you to verify a phone number synchronously. It is suitable for situations where immediate verification results are required, but it may be less efficient in handling high traffic or network delays.
  {% endtab %}
  {% endtabs %}

### API Documentation

This section provides a detailed overview of all available API endpoints for the Phone Number Verification service.

{% openapi src="/files/pEXBV2VQunNyJI4wSKWC" path="/v2/async-verify-phone" method="post" %}
[phone-number-verification.yaml](https://3401227780-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Ma8gvgl1y7j-M_RfiTg%2Fuploads%2Fgit-blob-887209fb91f06e377b92a4c81fea88126c989edd%2Fphone-number-verification.yaml?alt=media\&token=e7f0c174-4f4b-4425-9ace-cb6da4834acd)
{% endopenapi %}

{% openapi src="/files/pEXBV2VQunNyJI4wSKWC" path="/v2/verify-phone-number" method="post" %}
[phone-number-verification.yaml](https://3401227780-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Ma8gvgl1y7j-M_RfiTg%2Fuploads%2Fgit-blob-887209fb91f06e377b92a4c81fea88126c989edd%2Fphone-number-verification.yaml?alt=media\&token=e7f0c174-4f4b-4425-9ace-cb6da4834acd)
{% endopenapi %}

## Request Headers

<table data-full-width="true"><thead><tr><th>Header</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><code>smileid-partner-id</code></td><td>Your Smile ID partner ID.</td><td><code>002</code></td></tr><tr><td><code>smileid-request-signature</code></td><td>A signature to authenticate the request.</td><td><code>sample-signature</code></td></tr><tr><td><code>smileid-timestamp</code></td><td>The timestamp of the request.</td><td><code>2024-07-30T19:16:56.426Z</code></td></tr><tr><td><code>smileid-source-sdk</code></td><td>The source SDK identifier.</td><td><code>rest_api</code></td></tr><tr><td><code>smileid-source-sdk-version</code></td><td>The version of the source SDK.</td><td><code>1.0.0</code></td></tr></tbody></table>

## Request Body Example

```json
{
    "callback_url": "https://webhook.site/c5b9a01f-f224-494a-86b8-39ffe0c292a4",
    "country": "ZA",
    "phone_number": "0000000000",
    "match_fields": {
        "first_name": "Test",
        "last_name": "Test",
        "other_name": "Test",
        "id_number": "1234567890"
    }
}
```

{% hint style="success" %}
One of the following operators is required for the Ghana Phone Number verification: `MTN`, `VODAFONE`, or `AIRTELTIGO`

e.g "operator": "MTN"
{% endhint %}

{% hint style="warning" %}
**The match\_fields object contains the fields you intend to compare for a match or no match**
{% endhint %}

## Response

### Asynchronous Endpoint (`/v2/async-verify-phone`)

<table data-full-width="true"><thead><tr><th>Status Code</th><th>Description</th><th>Response Body</th></tr></thead><tbody><tr><td><code>200</code></td><td>Success</td><td><code>{ "success": true }</code></td></tr><tr><td><code>400</code></td><td>Bad request</td><td><code>{ "success": false, "code": "2413", "error": "Invalid request" }</code></td></tr><tr><td><code>500</code></td><td>Internal server error</td><td><code>{ "success": false, "error": "System Error" }</code></td></tr></tbody></table>

### Synchronous Endpoint (`/v2/verify-phone-number`)

<table data-full-width="true"><thead><tr><th>Status Code</th><th>Description</th><th>Response Body</th></tr></thead><tbody><tr><td><code>200</code></td><td>Success</td><td>Full JSON example below</td></tr><tr><td><code>400</code></td><td>Bad request</td><td><code>{ "success": false, "code": "2413", "error": "Invalid request" }</code></td></tr><tr><td><code>500</code></td><td>Internal server error</td><td><code>{ "success": false, "error": "System Error" }</code></td></tr></tbody></table>

**Example JSON Response:**

```json
{
  "code": "1020",
  "created_at": "2024-08-05T11:09:20.232Z",
  "job_id": "12cf30bb-d181-4d5e-a804-83253bafe6e4",
  "job_type": "phone_number_verification",
  "matched_fields": {
    "first_name": "Exact Match",
    "last_name": "Exact Match"
  },
  "message": "Exact Match",
  "partner_id": "002",
  "partner_params": {
    "job_id": "12cf30bb-d181-4d5e-a804-83253bafe6e4",
    "user_id": "8a1ccd25-b6e6-47ca-ab48-df5439b4613c"
  },
  "signature": "sample-signature",
  "timestamp": "2024-08-05T11:09:20.232Z"
}
```

## Result Codes

<table data-full-width="true"><thead><tr><th>Result Code</th><th>Message</th><th>Description</th></tr></thead><tbody><tr><td><code>1020</code></td><td>Exact Match</td><td>All fields provided match the record in the database.</td></tr><tr><td><code>1021</code></td><td>Partial Match</td><td>Some, but not all, fields match the record in the database.</td></tr><tr><td><code>1022</code></td><td>No Match</td><td>None of the fields match the record in the database.</td></tr><tr><td><code>1023</code></td><td>Record Not Found</td><td>The phone number does not exist in the database.</td></tr><tr><td><code>1015</code></td><td>ID Authority Unavailable</td><td>The verification could not be completed because the ID authority was unavailable.</td></tr></tbody></table>

## How Field Matching is Managed

Due to the unique characteristics of databases in different markets, the method we use to compare match fields with phone number records may vary.

<table data-full-width="true"><thead><tr><th>Field</th><th>Ghana</th><th>South Africa</th><th>Tanzania</th><th>Uganda</th></tr></thead><tbody><tr><td>First Name</td><td>Exact Match, Partial Match &#x26; No Match</td><td>Exact Match, Partial Match &#x26; No Match</td><td>Exact Match, Partial Match &#x26; No Match</td><td>Exact Match, Partial Match &#x26; No Match</td></tr><tr><td>Other Name</td><td>Exact Match, Partial Match &#x26; No Match</td><td>Exact Match, Partial Match &#x26; No Match</td><td>Exact Match, Partial Match &#x26; No Match</td><td>Exact Match, Partial Match &#x26; No Match</td></tr><tr><td>Last Name</td><td>Exact Match, Partial Match &#x26; No Match</td><td>Exact Match, Partial Match &#x26; No Match</td><td>Exact Match, Partial Match &#x26; No Match</td><td>Exact Match, Partial Match &#x26; No Match</td></tr><tr><td>ID Number</td><td>Not Applicable</td><td>Exact Match, Partial Match &#x26; No Match</td><td>Not Applicable</td><td>Not Applicable</td></tr></tbody></table>

* Exact Match: Fields match exactly
* Partial Match: Fields are a [levenshtein distance](https://en.wikipedia.org/wiki/Levenshtein_distance) of `<=2` apart
* No Match: All other cases


---

# 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/phone-number-verification.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.