# HLR lookups API

Ask the mobile networks about a number: its current carrier and MCC/MNC, whether it has been ported and whether it is roaming. Each lookup costs $0.05 and is charged as soon as it is sent.

## Look up a number (buyer)

`POST https://apiv2.telecomsxchange.com/buyers/hlr/lookup/{number}`

Reference: https://help.telecomsxchange.com/reference/hlr/#look-up-a-number-buyer

Runs a live HLR lookup on a mobile number and returns its current and original network, MCC/MNC (`network_code`), porting status and roaming status. Each lookup costs $0.05, charged to the buyer account you name and shown in its transactions as "HLR Lookup <number>".

> Each lookup costs $0.05, including lookups the network can't answer. Leading zeros in the number are dropped, so always send the full international number.

### Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `number` | string | path | yes | Number in international format, digits only, with no + or leading zeros. Example `447700900123`. |
| `i_account` | integer | body | yes | ID of the buyer account to charge. Its balance plus credit limit must be at least $0.05. Example `1501`. |

### Errors

| Message | When |
|---|---|
| `Account error` | `i_account` is missing or is not one of your accounts |
| `Account balance insufficient to run query` | the account's balance plus credit limit is below $0.05 |
| `CLD missing, or wrong format (only digits are supported)` | the number is not all digits |
| `{"status": "error", "response": {...}}` | the network cannot answer for this number or does not reply in time; `response` carries the provider's status and status_message |

### Request

```bash
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  "https://apiv2.telecomsxchange.com/buyers/hlr/lookup/447700900123" \
  -d i_account=1501
```

### Response: Example

```json
{
  "status": "success",
  "response": {
    "status": 0,
    "status_message": "Success",
    "request_id": "aa0e2a3c-5d1b-4f6e-9c1a-3f2b7d8e9a10",
    "international_format_number": "447700900123",
    "national_format_number": "07700 900123",
    "country_code": "GB",
    "country_code_iso3": "GBR",
    "country_name": "United Kingdom",
    "country_prefix": "44",
    "current_carrier": {
      "network_code": "23415",
      "name": "Vodafone Limited",
      "country": "GB",
      "network_type": "mobile"
    },
    "original_carrier": {
      "network_code": "23410",
      "name": "Telefonica UK Limited",
      "country": "GB",
      "network_type": "mobile"
    },
    "ported": "ported",
    "roaming": {
      "status": "unknown"
    }
  }
}
```

## Look up a number (seller)

`POST https://apiv2.telecomsxchange.com/sellers/hlr/lookup/{number}`

Reference: https://help.telecomsxchange.com/reference/hlr/#look-up-a-number-seller

Runs a live HLR lookup on a mobile number with seller credentials and returns its current and original network, MCC/MNC (`network_code`), porting status and roaming status. Each lookup costs $0.05, deducted from your seller balance and listed in your payouts as "HLR Lookup <number>".

> Each lookup costs $0.05, including lookups the network can't answer.

### Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `number` | string | path | yes | Number in international format, digits only, with no + or leading zeros. Example `447700900123`. |

### Errors

| Message | When |
|---|---|
| `Seller balance insufficient to run query` | your seller balance is below $0.05 |
| `CLD missing, or wrong format (only digits are supported)` | the number is not all digits |
| `{"status": "error", "response": {...}}` | the network cannot answer for this number or does not reply in time |

### Request

```bash
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  "https://apiv2.telecomsxchange.com/sellers/hlr/lookup/447700900123"
```

### Response: Example

```json
{
  "status": "success",
  "response": {
    "status": 0,
    "status_message": "Success",
    "request_id": "c41f8b20-77e9-4d3a-a5b6-0e9d1c2b3a45",
    "international_format_number": "447700900123",
    "national_format_number": "07700 900123",
    "country_code": "GB",
    "country_code_iso3": "GBR",
    "country_name": "United Kingdom",
    "country_prefix": "44",
    "current_carrier": {
      "network_code": "23415",
      "name": "Vodafone Limited",
      "country": "GB",
      "network_type": "mobile"
    },
    "original_carrier": {
      "network_code": "23415",
      "name": "Vodafone Limited",
      "country": "GB",
      "network_type": "mobile"
    },
    "ported": "not_ported",
    "roaming": {
      "status": "unknown"
    }
  }
}
```