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.

GET /hlr

Required Permission

create:HLR

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

Example Request

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.

All endpoints shown in this documentation use a sample base URL. The production API endpoint is provided by our team upon request.

Query Parameters

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

Response (HTTP 200)

{
  "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.

You can lookup multiple MSISDNs at once using a comma separated list.