> 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/address-verification.md).
# 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](https://docs.usesmileid.com/integration-options/rest-api). There is only one asynchronous endpoint available that allows for efficiency and ability to handle network delays better.
### Supported Countries
{% tabs %}
{% tab title="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}$/` |
| {% endtab %} | | |
{% tab title="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 |
| full\_name | The full\_name field is optional.
This field represents the registered owner of the utility meter. If the full name is unknown, the field may be omitted from the request body.
However, when a value is provided for full\_name, the system will perform a name comparison check against the meter owner’s records.
| 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 |
| {% endtab %} | |
| {% endtabs %} | |
### 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
> This endpoint verifies a address asynchronously.
```json
{"openapi":"3.0.3","info":{"title":"Smile Identity Address Verification API","version":"1.0.0"},"servers":[{"url":"https://api.smileidentity.com","description":"Production"},{"url":"https://testapi.smileidentity.com","description":"Sandbox"},{"url":"https://devapi.smileidentity.com","description":"Development"}],"paths":{"/v2/async-verify-address":{"post":{"summary":"Asynchronously verify a address","description":"This endpoint verifies a address asynchronously.","parameters":[{"$ref":"#/components/parameters/SmileIdPartnerId"},{"$ref":"#/components/parameters/SmileIdRequestSignature"},{"$ref":"#/components/parameters/SmileIdTimestamp"},{"$ref":"#/components/parameters/SmileIdSourceSdk"},{"$ref":"#/components/parameters/SmileIdSourceSdkVersion"}],"requestBody":{"$ref":"#/components/requestBodies/VerifyAddress"},"responses":{"200":{"description":"A successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"code":{"type":"string"},"error":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}}}}}}}}}},"components":{"parameters":{"SmileIdPartnerId":{"name":"smileid-partner-id","in":"header","required":true,"schema":{"type":"string"}},"SmileIdRequestSignature":{"name":"smileid-request-signature","in":"header","required":true,"schema":{"type":"string"}},"SmileIdTimestamp":{"name":"smileid-timestamp","in":"header","required":true,"schema":{"type":"string"}},"SmileIdSourceSdk":{"name":"smileid-source-sdk","in":"header","required":true,"schema":{"type":"string"}},"SmileIdSourceSdkVersion":{"name":"smileid-source-sdk-version","in":"header","required":true,"schema":{"type":"string"}}},"requestBodies":{"VerifyAddress":{"description":"Request body for verifying a address","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"callback_url":{"type":"string","format":"uri"},"country":{"type":"string","enum":["NG","ZA"]},"address":{"type":"string"},"full_name":{"type":"string"},"utility_number":{"type":"string"},"id_number":{"type":"string","pattern":"^[0-9]{13}$"},"utility_provider":{"type":"string","enum":["AEDC","BEDC","EKEDC","IBEDC","IKEDC","JEDC","KAEDCO","KEDCO","PHEDC","YEDC","EEDC"]},"utility_type":{"type":"string","enum":["PrePaid","PostPaid"]}},"required":["callback_url","country","address"],"oneOf":[{"required":["id_number"]},{"required":["utility_number"]}]}}}}}}}
```
### 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
{% tabs %}
{% tab title="South Africa (ZA)" %}
```json
{
"country": "ZA",
"address": "cape town",
"id_number": "1234343545454",
"full_name": "Joe Doe Leo",
"callback_url": "https://webhook.site/5c23fe74-0e5d-470c-b528-ce6f3211b48f",
"partner_params": {
"user_id": "test_user_id",
"job_id": "test_job_id"
}
}
```
{% endtab %}
{% tab title="Nigeria (NG)" %}
```json
{
"callback_url": "https://webhook.site/c1dd8434-6521-4b10-8246-c147e3a5e68e",
"country": "NG",
"address": "10, Workbox, Ojora Close, Victoria Island, Lagos, Mushin, Lagos State",
"full_name": "John Doe Leo",
"utility_number": "00000000000",
"utility_provider": "PHEDC",
"utility_type": "PrePaid",
"partner_params": {
"user_id": "test_user_id",
"job_id": "test_job_id"
}
}
```
{% endtab %}
{% endtabs %}
### 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
```json
{
"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 more 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. |
---
# 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/address-verification.md?ask=&goal=
```
`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.