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

# Lookup Phone Number

> Retrieve carrier and subscriber information for a Nigerian phone number. Returns network, line type, and identity details when available.

<Note>
  There are two payload responses for this endpoint based on the details returned:

  * **Basic**
  * **Advanced**
</Note>

## Phone Number Basic

```http [GET] theme={null}
{{baseUrl}}api/v1/kyc/phone_number/basic

```

### Header

| Header        | Type   | Description                                                                                         |
| ------------- | ------ | --------------------------------------------------------------------------------------------------- |
| AppId         | string | Create an app to get your app ID on dashboard [here](https://app.dojah.io/developers/configuration) |
| Authorization | string | Private/secret key. Use `<key>` not `Bearer <key>`                                                  |

### Query parameters

| Parameter        | Type   | Description          | Required |
| ---------------- | ------ | -------------------- | -------- |
| phone\_number \* | string | A valid phone number | required |

### Sample response

```json Response theme={null}
{
    "entity": {
        "first_name": "JOHN",
        "middle_name": "DOE",
        "last_name": "MUSA",
        "gender": "Male",
        "nationality": "NGA",
        "date_of_birth": "1990-05-16",
        "msisdn": "23481222222222"
    }
}
```

### Response Fields

| Field                  | Type   | Description                                            |
| ---------------------- | ------ | ------------------------------------------------------ |
| entity                 | object | Contains the phone number lookup response data         |
| entity.first\_name     | string | First name of the phone number subscriber              |
| entity.middle\_name    | string | Middle name of the phone number subscriber             |
| entity.last\_name      | string | Last name of the phone number subscriber               |
| entity.gender          | string | Gender of the subscriber                               |
| entity.nationality     | string | Nationality code of the subscriber (e.g., NGA)         |
| entity.date\_of\_birth | string | Date of birth of the subscriber (YYYY-MM-DD)           |
| entity.msisdn          | string | Full MSISDN (international format) of the phone number |

## Phone Number Advance

```http [GET] theme={null}
{{baseUrl}}api/v1/kyc/phone_number?phone_number=081123456976
```

### Query parameters

| Parameter        | Type   | Description         | Required |
| ---------------- | ------ | ------------------- | -------- |
| phone\_number \* | string | A valid phone numbe | required |

### Sample response

```json Response theme={null}
{
    "entity": {
        "first_name": "JOHN",
        "last_name": "MUSA",
        "middle_name": "DOE",
        "date_of_birth": "1960-12-12",
        "phone_number": "08012345678",
        "photo": "BASE 64 IMAGE",
        "gender": "M",
        "customer": "9b2ac137-5360-4050-b412-4fa6728a31fb"
    }
}
```

### Response Fields

| Field                  | Type   | Description                                             |
| ---------------------- | ------ | ------------------------------------------------------- |
| entity                 | object | Contains the advanced phone number lookup response data |
| entity.first\_name     | string | First name of the phone number subscriber               |
| entity.last\_name      | string | Last name of the phone number subscriber                |
| entity.middle\_name    | string | Middle name of the phone number subscriber              |
| entity.date\_of\_birth | string | Date of birth of the subscriber (YYYY-MM-DD)            |
| entity.phone\_number   | string | Phone number that was looked up                         |
| entity.photo           | string | Base64-encoded photo of the subscriber                  |
| entity.gender          | string | Gender of the subscriber                                |
| entity.customer        | string | Unique customer identifier (UUID)                       |

### Test Credentials for Sandbox

phone\_number = `09011111111`