Skip to main content
The Address Lookup by NIN endpoint retrieves a customer’s previously verified address based on their NIN and personal details. Use time_range to filter results to addresses verified within a minimum number of months.

​
Endpoint

POST /api/onboarding/nigeria_kyc/identity_address/

​
Request

​
Headers

HeaderValueRequired
x-access-tokenYour API secret keyYes
Content-Typeapplication/jsonYes

​
Body Parameters

ParameterTypeRequiredDescription
first_namestringYesCustomer’s first name
last_namestringYesCustomer’s last name
ninstringYesCustomer’s 11-digit NIN
phone_numberstringYesCustomer’s phone number
statestringYesState to search within
time_rangeintegerYesMinimum months since the address was verified (e.g. 6 for addresses verified within the last 6 months)

​
Example

curl -X POST "https://adhere-api.smartcomply.com/api/onboarding/nigeria_kyc/identity_address/" \
  -H "x-access-token: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John", "last_name": "Doe",
    "nin": "10000000001", "phone_number": "08000000000",
    "state": "Lagos", "time_range": 2
  }'

​
Response

​
200 OK

FieldTypeDescription
data.idintegerVerification record ID
data.applicantobjectVerified applicant details
data.lattitudestringGeocoded latitude of the address
data.longitudestringGeocoded longitude of the address
data.photosarrayPhotos captured during field verification
data.neighborobjectNeighbor confirmation details
data.statusobjectCurrent verification status
data.referencestringUnique reference for the verification record
{
  "status": "success",
  "data": {
    "id": 1,
    "applicant": {
      "firstname": "John",
      "lastname": "Doe",
      "phone": "08000000000",
      "idType": "nin",
      "idNumber": "10000000001",
      "middlename": "Cameron",
      "gender": "Male",
      "birthdate": "17/01/1988"
    },
    "createdAt": "",
    "completedAt": "",
    "lattitude": "9.081999",
    "longitude": "8.675277",
    "photos": [
      "https://picsum.photos/id/768/200/300.jpg"
    ],
    "neighbor": {
      "name": "Tunde Adetunji",
      "comment": "Very friendly",
      "phone": "080900000000"
    },
    "status": {
      "status": "In Progress",
      "subStatus": "In Progress",
      "state": "In Progress"
    },
    "city": "oshodi",
    "street": "270 Murtala Muhammed Way, Alagomeji. Yaba",
    "lga": "lagos mainland",
    "state": "Lagos",
    "country": "Nigeria",
    "reference": "1732800207805106"
  },
  "message": "Address details retrieved successfully"
}

​
400 Bad Request

{
  "status": "failed",
  "data": [],
  "message": "Missing required fields"
}

​
401 Unauthorized

{
  "status": "failed",
  "message": "Authentication credentials were not provided."
}