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 Kenya, Nigeria, South Africa, Tanzania and Uganda covering over 330 million phone numbers across these regions.

Integration Options

Only available via the REST APIs. 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

Country	Phone Number Regex	Match Fields
Kenya	/^[0-9]{10}$/	ID Number
Nigeria	/^[0-9]{11}$/	First Name, Other Name, Last Name
South Africa	/^[0-9]{10}$/	First Name, Other Name, Last Name, ID Number
Tanzania	/^[0-9]{12}$/	First Name, Other Name, Last Name
Uganda	/^[0-9]{10}$/	First Name, Other Name, Last Name

Testing the Product in Sandbox

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

Country	Test Phone Number	Test Last Name	Test First Name	Test Other Name	Test ID Number
Kenya	0000000000	N/A	N/A	N/A	00000000
Nigeria	00000000000	Leo	Joe	N/A	N/A
South Africa	0000000000	Leo	Joe	Doe	0000000000000
Tanzania	000000000000	Leo	Joe	Doe	N/A
Uganda	0000000000	Leo	Joe	Doe	N/A

How to Use the Test Data

There are four simulated Results to test your integration:

Final Digit	Simulated Result	Code
0 e.g. 0000000000	Varies based on match_fields	Varies based on match_fields
1 e.g0000000001	Failure, no record found	1023
2 e.g. 0000000002	Invalid phone number format	2413
3 e.g. 0000000003	Database unavailable/unknown network issue	1015

Endpoints

Asynchronous vs. Synchronous Endpoints

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.

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.

API Documentation

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

Asynchronously verify a phone number

post

This endpoint verifies a phone number asynchronously.

Header parameters

smileid-partner-idstringRequiredExample: 002

smileid-request-signaturestringRequiredExample: sample-signature

smileid-timestampstringRequiredExample: 2024-07-30T19:16:56.426Z

smileid-source-sdkstringRequiredExample: sample-source

smileid-source-sdk-versionstringRequiredExample: 0.0.1

Body

callback_urlstring · uriRequiredExample: https://webhook.site/c5b9a01f-f224-494a-86b8-39ffe0c292a4

countrystringRequiredExample: ZA

phone_numberstringRequiredExample: 0000000000

Responses

200

A successful response

application/json

400

Bad request

application/json

500

Internal server error

application/json

post

HTTPcURLJavaScriptPython

POST /v2/async-verify-phone HTTP/1.1
Host: api.smileidentity.com
smileid-partner-id: 002
smileid-request-signature: sample-signature
smileid-timestamp: 2024-07-30T19:16:56.426Z
smileid-source-sdk: sample-source
smileid-source-sdk-version: 0.0.1
Content-Type: application/json
Accept: */*
Content-Length: 214

{
  "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": "text"
  }
}

{
  "success": true
}

Verify a phone number synchronously

post

This endpoint verifies a phone number synchronously.

Header parameters

smileid-partner-idstringRequiredExample: 002

smileid-request-signaturestringRequiredExample: sample-signature

smileid-timestampstringRequiredExample: 2024-07-30T19:16:56.426Z

smileid-source-sdkstringRequiredExample: sample-source

smileid-source-sdk-versionstringRequiredExample: 0.0.1

Body

callback_urlstring · uriRequiredExample: https://webhook.site/c5b9a01f-f224-494a-86b8-39ffe0c292a4

countrystringRequiredExample: ZA

phone_numberstringRequiredExample: 0000000000

Responses

200

A successful response

application/json

400

Bad request

application/json

500

Internal server error

application/json

post

HTTPcURLJavaScriptPython

POST /v2/verify-phone-number HTTP/1.1
Host: api.smileidentity.com
smileid-partner-id: 002
smileid-request-signature: sample-signature
smileid-timestamp: 2024-07-30T19:16:56.426Z
smileid-source-sdk: sample-source
smileid-source-sdk-version: 0.0.1
Content-Type: application/json
Accept: */*
Content-Length: 214

{
  "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": "text"
  }
}

{
  "code": "2413",
  "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"
}

Request Headers

Header	Description	Example
smileid-partner-id	Your Smile ID partner ID.	002
smileid-request-signature	A signature to authenticate the request.	sample-signature
smileid-timestamp	The timestamp of the request.	2024-07-30T19:16:56.426Z
smileid-source-sdk	The source SDK identifier.	rest_api
smileid-source-sdk-version	The version of the source SDK.	1.0.0

Request Body Example

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

Response

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

Status Code	Description	Response Body
200	Success	{ "success": true }
400	Bad request	{ "success": false, "code": "2413", "error": "Invalid request" }
500	Internal server error	{ "success": false, "error": "System Error" }

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

Status Code	Description	Response Body
200	Success	Full JSON example below
400	Bad request	{ "success": false, "code": "2413", "error": "Invalid request" }
500	Internal server error	{ "success": false, "error": "System Error" }

Example JSON Response:

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

Result Code	Message	Description
1020	Exact Match	All fields provided match the record in the database.
1021	Partial Match	Some, but not all, fields match the record in the database.
1022	No Match	None of the fields match the record in the database.
1023	Record Not Found	The phone number does not exist in the database.
1015	ID Authority Unavailable	The verification could not be completed because the ID authority was unavailable.

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.

Field	Kenya	Nigeria	South Africa	Tanzania	Uganda
First Name	Not Applicable	Exact Match, Partial Match & No Match	Exact Match, Partial Match & No Match	Exact Match, Partial Match & No Match	Exact Match, Partial Match & No Match
Other Name	Not Applicable	Not Applicable	Exact Match, Partial Match & No Match	Exact Match, Partial Match & No Match	Exact Match, Partial Match & No Match
Last Name	Not Applicable	Exact Match, Partial Match & No Match	Exact Match, Partial Match & No Match	Exact Match, Partial Match & No Match	Exact Match, Partial Match & No Match
ID Number	Exact Match & No Match only	Not Applicable	Exact Match, Partial Match & No Match	Not Applicable	Not Applicable

• Exact Match: Fields match exactly

• Partial Match: Fields are a levenshtein distance of <=2 apart
• No Match: All other cases