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

# Number Lookup

> Validate phone numbers and retrieve carrier information with HLR/MNP lookup

## Overview

Number lookup provides real-time carrier information, porting status, and number type validation using HLR (Home Location Register) and MNP (Mobile Number Portability) queries.

**What you get:**

* Carrier name and network codes (MCC/MNC)
* Porting status (original vs current carrier)
* Number type (mobile, landline, VoIP)
* Country and region information

## Single Lookup

```bash cURL theme={null}
curl -X POST https://api-message.nativehub.live/api/v1/numbers/lookup \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+8801712345678"
  }'
```

```javascript Node.js theme={null}
const response = await fetch('https://api-message.nativehub.live/api/v1/numbers/lookup', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    phone: '+8801712345678'
  })
});

const data = await response.json();
console.log(data);
```

```python Python theme={null}
import requests

response = requests.post(
    'https://api-message.nativehub.live/api/v1/numbers/lookup',
    headers={
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Content-Type': 'application/json'
    },
    json={'phone': '+8801712345678'}
)

data = response.json()
print(data)
```

**Response:**

```json theme={null}
{
  "phone": "+8801712345678",
  "country_code": "BD",
  "country_name": "Bangladesh",
  "carrier": "Grameenphone",
  "is_ported": false,
  "is_mobile": true,
  "mcc": "470",
  "mnc": "01"
}
```

## Batch Lookup

Process multiple numbers in a single request.

```bash cURL theme={null}
curl -X POST https://api-message.nativehub.live/api/v1/numbers/lookup/batch \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "numbers": ["+8801712345678", "+8801812345679", "+8801912345680"]
  }'
```

```javascript Node.js theme={null}
const response = await fetch('https://api-message.nativehub.live/api/v1/numbers/lookup/batch', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    numbers: ['+8801712345678', '+8801812345679', '+8801912345680']
  })
});

const results = await response.json();
```

```python Python theme={null}
response = requests.post(
    'https://api-message.nativehub.live/api/v1/numbers/lookup/batch',
    headers={
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Content-Type': 'application/json'
    },
    json={'numbers': ['+8801712345678', '+8801812345679', '+8801912345680']}
)

results = response.json()
```

## Lookup History

Retrieve past lookup results.

```bash cURL theme={null}
curl -X GET https://api-message.nativehub.live/api/v1/numbers/lookup \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

**Lookup by phone:**

```bash cURL theme={null}
curl -X GET https://api-message.nativehub.live/api/v1/numbers/lookup/+8801712345678 \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

## Use Cases

| Use Case              | Benefit                                                          |
| --------------------- | ---------------------------------------------------------------- |
| Pre-send validation   | Avoid sending to invalid or inactive numbers                     |
| Contact list cleaning | Remove landlines and non-mobile numbers from SMS campaigns       |
| Cost optimization     | Route messages through cheapest carrier based on current network |
| Fraud prevention      | Detect VoIP numbers or suspicious porting patterns               |
| Analytics             | Track carrier distribution in your contact database              |

<Note>
  Lookup results are cached for 24 hours. Numbers may port between carriers, so periodic re-validation is recommended for critical use cases.
</Note>

## Response Fields

| Field          | Type    | Description                                           |
| -------------- | ------- | ----------------------------------------------------- |
| `phone`        | string  | Phone number in E.164 format                          |
| `country_code` | string  | ISO 3166-1 alpha-2 country code                       |
| `country_name` | string  | Full country name                                     |
| `carrier`      | string  | Current carrier/operator name                         |
| `is_ported`    | boolean | Whether number has been ported to a different carrier |
| `is_mobile`    | boolean | Whether number is a mobile device (vs landline/VoIP)  |
| `mcc`          | string  | Mobile Country Code                                   |
| `mnc`          | string  | Mobile Network Code                                   |