All file links (e.g. selfie URLs, document URLs) returned in the response expire within one hour. We strongly recommend transferring these documents and images to your own infrastructure as soon as you receive them. If a link expires before you are able to download the file, call the Fetch Address Verification Data endpoint to generate a new link — which will also expire in one hour.
Request
[GET]
{{baseUrl}}/api/v1/kyc/address
Header
| Header | Type | Description |
|---|---|---|
| AppId | string | Create an app to get your app ID on dashboard here |
| Authorization | string | Private/secret key. Use <key> not Bearer <key> |
Query parameter
| Parameter | Type | Description | Required |
|---|---|---|---|
| reference_id | string | 69e10264-4b90-64fe-b4b7-c9dddafd0241 | required |
Sample response
Response
{
"entity": {
"status":"pending",
"reference_id": "69e10264-4b90-64fe-b4b7-c9dddafd0241",
"data": {
"applicant": {
"first_name": "John",
"last_name": "Musa",
"phone": "08012345678",
"middle_name": "Doe",
"photo": "",
"gender": "Male",
"dob": "17/01/1988"
},
"location": "7.081273, 8.232523",
"photos": [
""
],
"neighbor": {
"name": "Musa Garba",
"comment": "Very friendly",
"phone": "080987654321"
},
"city": "oshodi",
"street": "270 Murtala Muhammed Way, Alagomeji. Yaba",
"lga": "lagos mainland",
"state": "Lagos",
"country": "Nigeria",
"comments": ""
}
}
}
Response Fields
| Field | Type | Description |
|---|---|---|
| entity | object | Contains the response data |
| entity.status | string | Verification status. Values: pending (verification in progress), completed (verification finished), failed (verification could not be completed) |
| entity.reference_id | string | Unique reference ID for the verification request |
| entity.data | object | Detailed verification data (populated when status is completed) |
| entity.data.applicant | object | Information about the individual whose address was verified |
| entity.data.applicant.first_name | string | First name of the applicant |
| entity.data.applicant.last_name | string | Last name of the applicant |
| entity.data.applicant.phone | string | Phone number of the applicant |
| entity.data.applicant.middle_name | string | Middle name of the applicant |
| entity.data.applicant.photo | string | URL or Base64 of the applicant’s photo (may be empty) |
| entity.data.applicant.gender | string | Gender of the applicant |
| entity.data.applicant.dob | string | Date of birth of the applicant (DD/MM/YYYY format) |
| entity.data.location | string | GPS coordinates of the verified address (latitude, longitude) |
| entity.data.photos | array | List of photo URLs or Base64 strings taken during verification |
| entity.data.neighbor | object | Information collected from a neighbor during verification |
| entity.data.neighbor.name | string | Name of the neighbor contacted |
| entity.data.neighbor.comment | string | Neighbor’s comment about the applicant |
| entity.data.neighbor.phone | string | Phone number of the neighbor |
| entity.data.city | string | City of the verified address |
| entity.data.street | string | Street address that was verified |
| entity.data.lga | string | Local Government Area of the address |
| entity.data.state | string | State of the verified address |
| entity.data.country | string | Country of the verified address |
| entity.data.comments | string | Additional comments from the verification agent |