Digital Address Verification

Overview

The Digital 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_type	user's electricity meter type - PrePaid or PostPaid	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
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	PHEDC
Yola Electricity Distribution Company	YEDC

Testing The Product in Sandbox

You can evaluate the Digital 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 Digital Address verification.

Asynchronously verify a address

post

This endpoint verifies a address 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://example.com

countrystring · enumRequiredExample: ZAPossible values:

addressstringRequiredExample: cape town

full_namestringOptionalExample: Joe Doe

utility_numberstringOptionalExample: 0000000000

id_numberstringOptionalExample: 0000000000000Pattern: ^[0-9]{13}$

utility_providerstring · enumOptionalExample: EKEDCPossible values:

utility_typestring · enumOptionalExample: PrePaidPossible values:

Responses

200

A successful response

application/json

400

Bad request

application/json

500

Internal server error

application/json

post

HTTPcURLJavaScriptPython

POST /v2/async-verify-address 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: 207

{
  "callback_url": "https://example.com",
  "country": "ZA",
  "address": "cape town",
  "full_name": "Joe Doe",
  "utility_number": "0000000000",
  "id_number": "0000000000000",
  "utility_provider": "EKEDC",
  "utility_type": "PrePaid"
}

{
  "success": true
}

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.