# REST API — Number Lookup (HLR)


Source: https://vertexsms.com/en/api/hlr

HLR (Home Location Register) lookup determines the current service provider of a mobile subscriber.

```
POST https://api.vertexsms.com/hlr
```

Submits the provided `msisdn` for HLR lookup. On success returns HTTP `200 OK`.

## Required parameters

| Field | Type | Description |
|-------|------|-------------|
| msisdn | string | International subscriber number to look up. |
| callBackUrl | url | Where to deliver the HLR result. |

### Request example

```
POST /hlr HTTP/1.1
Host: api.vertexsms.com
Content-Type: application/json
Accept: application/json
X-VertexSMS-Token: eB52vNTPL9fO3rDrx8pYmVnj6nqceHNhnqceHNh

{ "msisdn": "37069912345", "callBackUrl": "http://api.vertexsms.com/hlr_callback?myRequestId=123456" }
```

### Response example

```
HTTP/1.1 200 OK
Content-Type: application/json
Cache-control: no-cache

[1203877133]
```

## HLR lookup callback

After the lookup completes, VertexSMS POSTs the result to your `callBackUrl`:

```
POST /your_script.php HTTP/1.1
Host: yourserver.com
Content-Type: application/json

{ "id": "1203877133", "error": "0", "imsi": "2460210051600001", "country": "LT", "mcc": "246", "mnc": "021" }
```

Callback fields:

| Field | Type | Description |
|-------|------|-------------|
| id | string | Unique HLR lookup identifier returned at submission. |
| error | integer | VertexSMS error code (see Error codes). |
| imsi | integer | International mobile subscriber identity. |
| country | string | ISO 3166-1 alpha-2 country code. |
| operatorId | integer | Internal VertexSMS operator identifier. |
| mcc | string | Mobile country code. |
| mnc | string | Mobile network code. |
| ported | array | Present if the number is ported. Contains `operatorId`, `operator` (origin operator name), `country`. |

**Your callback endpoint MUST respond `200 OK` with body `OK`.** Otherwise the callback is retried until it succeeds.