Address Verification

Overview

The Address Verification product is a solution designed to verify customer address using their id numbers and utility numbers. This product is especially beneficial for businesses that want to ensure the legitimacy of the address information provided by my customers for improved service delivery and risk management. The service is currently available in Nigeria, and South Africa.

Integrations Options

Only available via the REST APIs. There is only one asynchronous endpoint available that allows for efficiency and ability to handle network delays better.

Supported Countries

South Africa (ZA)

Required Fields

Field Name	Description	Regex
address	user's full address	Not Applicable
id_number	user's national id number	/^[0-9]{13}$/

Nigeria (NG)

Required Fields

Field name	Description	Regex
address	user's full address	Not Applicable
utility_number	user's electricity meter number	Not Applicable
utility_provider	user's electricity provider i.e DisCo. See full list of supported DisCos below	Not Applicable

Supported Utility Providers (DisCos)

Utility Provider	Value
Aba Power	ABA
Abuja Electricity Distribution Company	AEDC
Benin Electricity Distribution Company	BEDC
Eko Electricity Distribution Company	EKEDC
Enugu Electricity Distribution Company	EEDC
Ibadan Electricity Distribution Company	IBEDC
Ikeja Electricity Distribution Company	IKEDC
Jos Electricity Distribution Company	JEDC
Kaduna Electricity Distribution Company	KAEDCO
Kano Electricity Distribution Company	KEDCO
Port Harcourt Electricity Distribution Company	PEDC
Yola Electricity Distribution Company	YEDC

Testing The Product in Sandbox

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

Country	Test Full Name	Test ID/Utility Number
South Africa	Joe Doe Leo	0000000000000
Nigeria	Joe Doe Leo	0000000000

How to Use the Test Data

There are four simulated results to test your integration:

Final Digit	Simulated Result	Code
0 e.g 00000000	Varies based on searched address and full name matching	Varies based on searched address and full name matching
1 e.g 000000001	Verification failed: Unique identifier type not found.	1013
2 e.g 000000002	Invalid id or utility number format	2413
3 e.g 00000003	Database unavailable	1015
4 e.g 00000004	Simulating when addresses are too far apart.	1022

Endpoints

Asynchronous Endpoint

• Endpoint v2/async-verify-address

• Method: POST

• Description: This endpoint allows you to verify an address asynchronously. It is less prone to network related issues.

API Documentation

This section provides a detailed overview of the endpoint for Address verification.

Asynchronously verify a address

post

This endpoint verifies a address asynchronously.

Header parameters

smileid-partner-idstringrequired

Example: 002

smileid-request-signaturestringrequired

Example: sample-signature

smileid-timestampstringrequired

Example: 2024-07-30T19:16:56.426Z

smileid-source-sdkstringrequired

Example: sample-source

smileid-source-sdk-versionstringrequired

Example: 0.0.1

Body

callback_urlstring · urirequired

Example: https://webhook.site/c5b9a01f-f224-494a-86b8-39ffe0c292a4

countrystringrequired

Example: ZA

addressstringrequired

Example: cape town

full_namestringoptional

Example: Joe Doe

utility_numberstringoptional

Example: 123456789

id_numberstringoptional

Example: 123456789

utility_providerstringoptional

Example: test provider

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.smileidentity.com/v2/async-verify-address' \
  --header 'smileid-partner-id: 002' \
  --header 'smileid-request-signature: sample-signature' \
  --header 'smileid-timestamp: 2024-07-30T19:16:56.426Z' \
  --header 'smileid-source-sdk: sample-source' \
  --header 'smileid-source-sdk-version: 0.0.1' \
  --header 'Content-Type: application/json' \
  --data '{
    "callback_url": "https://webhook.site/c5b9a01f-f224-494a-86b8-39ffe0c292a4",
    "country": "ZA",
    "address": "cape town",
    "full_name": "Joe Doe",
    "utility_number": "123456789",
    "id_number": "123456789",
    "utility_provider": "test provider"
  }'

application/json

200

400

500

200

{
  "success": true
}

A successful response

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

{
  "country": "ZA", 
  "address": "cape town",
  "id_number": "1234343545454",
  "full_name": "Joe Doe Leo",
  "callback_url": "https://webhook.site/5c23fe74-0e5d-470c-b528-ce6f3211b48f"
}

Response

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

Callback Response

{
  "code": "1012",
  "created_at": "2024-11-29T15:44:58.357Z",
  "full_name": "JOE LEO DOE",
  "full_name_match": "Transposed",
  "job_id": "43bc1e54-736f-49af-9836-f7990fd2be39",
  "job_type": "address_verification",
  "matched_address": {
    "address_line_1": "Cape Town B45 111",
    "country": "ZA",
    "full_address": "Cape Town B45 111, South Africa",
    "gps_coordinates": "-25.7461,28.1881",
    "last_updated_at": "2024-11-15",
    "proximity": 0
  },
  "message": "Verification successful",
  "other_addresses": [
    {
      "address_line_1": "Cape Town B45 112",
      "country": "ZA",
      "full_address": "Cape Town B45 111, South Africa",
      "gps_coordinates": "-25.7461,28.1881",
      "last_updated_at": "2024-10-10",
      "proximity": 0
    },
    {
      "address_line_1": "Cape Town B45 113",
      "country": "ZA",
      "full_address": "Cape Town B45 111, South Africa",
      "gps_coordinates": "-25.7461,28.1881",
      "last_updated_at": "2024-06-30",
      "proximity": 0
    }
  ],
  "partner_id": "002",
  "partner_params": {
    "job_id": "mock-job-id",
    "user_id": "mock-user-id"
  },
  "signature": "mock-signature",
  "smile_job_id": "0000000",
  "submitted_address": {
    "address_line_1": "Cape Town",
    "address_line_2": "B45 111",
    "country": "ZA",
    "full_address": "Cape Town B45 111, South Africa",
    "gps_coordinates": "-25.7461,28.1881"
  },
  "timestamp": "2024-11-29T15:45:00.722Z"
}

Result Codes

Result Code	Message	Description
1012	Verification successful.	All checks are fine
1022	Verification failed: No address found within acceptable distance.	All addresses too far
1022	Verification failed: Provided name does not match name in records.	Full name doesn't match
1017	Warning: Address within acceptable distance, but information is outdated.	All addresses last updated date less than 6 months ago
1013	Verification failed: Unique identifier type not found.	Unique identifier is not found in the database
1015	Service unavailable: Data source is down, please try again later.	The verification could not be completed because the ID authority was unavailable.