# HLR (Number Lookup)

Perform a **synchronous HLR (Home Location Register) lookup** to get detailed information about one or more mobile numbers. This is useful for verifying number validity, detecting ported numbers, and understanding the network associated with each recipient.

### <mark style="color:green;">`GET`</mark> `/hlr`

#### Required Permission

```
create:HLR
```

Your API key must have this permission enabled in order to use this endpoint.

#### Example Request

```bash
curl --location 'https://<hostname>/hlr?lookup=4400000000000,4400000000001,4400000000002' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

Replace `YOUR_API_KEY` with your API key.

{% hint style="info" %}
All endpoints shown in this documentation use a **sample base URL**. The production API endpoint is provided by our team upon request.
{% endhint %}

### Query Parameters

| Parameter | Type   | Required | Description                                                                        |
| --------- | ------ | -------- | ---------------------------------------------------------------------------------- |
| lookup    | string | Yes      | Comma-separated list of MSISDNs (phone numbers in international format) to verify. |

#### Response (HTTP 200)

```json
{
  "success": true,
  "batchID": "0c040d34-e2a-460a-97dd-66ffc235a7",
  "results": [
    {
      "to": "4400000000000",
      "mccMnc": "23410",
      "imsi": "234100000000000",
      "originalNetwork": {
        "networkName": "MNO - BT - Everything Everywhere Limited",
        "networkPrefix": "79324",
        "countryName": "United Kingdom",
        "countryPrefix": "44",
        "networkId": 791
      },
      "ported": true,
      "portedNetwork": {
        "networkName": "MNO - Virgin Media O2 (Telefonica UK Ltd)",
        "networkPrefix": "76020",
        "countryName": "United Kingdom",
        "countryPrefix": "44",
        "networkId": 785
      },
      "status": {
        "groupId": 3,
        "groupName": "DELIVERED",
        "id": 5,
        "name": "DELIVERED_TO_HANDSET",
        "description": "Message delivered to handset"
      },
      "error": {
        "groupId": 0,
        "groupName": "OK",
        "id": 0,
        "name": "NO_ERROR",
        "description": "No Error",
        "permanent": false
      }
    }
  ]
}
```

### Response Fields

| Field           | Type    | Description                                                     |
| --------------- | ------- | --------------------------------------------------------------- |
| batchID         | string  | Unique ID for this HLR lookup batch.                            |
| results         | array   | Array of objects, one per number looked up.                     |
| to              | string  | The phone number queried.                                       |
| mccMnc          | string  | Mobile Country Code & Mobile Network Code.                      |
| imsi            | string  | International Mobile Subscriber Identity.                       |
| originalNetwork | object  | Details about the number’s original network.                    |
| ported          | boolean | Indicates if the number has been ported to a different network. |
| portedNetwork   | object  | Details of the network the number is ported to (if applicable). |
| status          | object  | Current delivery/status group of the number.                    |
| error           | object  | Any errors encountered during the lookup.                       |

{% hint style="info" %}
You can lookup multiple MSISDNs at once using a **comma separated list**.
{% endhint %}