> ## Documentation Index
> Fetch the complete documentation index at: https://docs.smartcomply.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Address Lookup by NIN

> Retrieve a customer's verified address history using their NIN and other identity details.

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

| Header           | Value               | Required |
| ---------------- | ------------------- | -------- |
| `x-access-token` | Your API secret key | Yes      |
| `Content-Type`   | `application/json`  | Yes      |

### Body Parameters

| Parameter      | Type    | Required | Description                                                                                              |
| -------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------- |
| `first_name`   | string  | Yes      | Customer's first name                                                                                    |
| `last_name`    | string  | Yes      | Customer's last name                                                                                     |
| `nin`          | string  | Yes      | Customer's 11-digit NIN                                                                                  |
| `phone_number` | string  | Yes      | Customer's phone number                                                                                  |
| `state`        | string  | Yes      | State to search within                                                                                   |
| `time_range`   | integer | Yes      | Minimum months since the address was verified (e.g. `6` for addresses verified within the last 6 months) |

### Example

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```
</CodeGroup>

## Response

### 200 OK

| Field            | Type    | Description                                  |
| ---------------- | ------- | -------------------------------------------- |
| `data.id`        | integer | Verification record ID                       |
| `data.applicant` | object  | Verified applicant details                   |
| `data.lattitude` | string  | Geocoded latitude of the address             |
| `data.longitude` | string  | Geocoded longitude of the address            |
| `data.photos`    | array   | Photos captured during field verification    |
| `data.neighbor`  | object  | Neighbor confirmation details                |
| `data.status`    | object  | Current verification status                  |
| `data.reference` | string  | Unique reference for the verification record |

```json theme={null}
{
  "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

```json theme={null}
{
  "status": "failed",
  "data": [],
  "message": "Missing required fields"
}
```

### 401 Unauthorized

```json theme={null}
{
  "status": "failed",
  "message": "Authentication credentials were not provided."
}
```