All API resources

HLR lookups

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.

POSTLook up a number (buyer)
POSTLook up a number (seller)

Look up a number (buyer)

POST/buyers/hlr/lookup/{number}

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

numberstringpathRequired
Number in international format, digits only, with no + or leading zeros.
Example447700900123
i_accountintegerform fieldRequired
ID of the buyer account to charge. Its balance plus credit limit must be at least $0.05.
Example1501

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

POST/buyers/hlr/lookup/{number}

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

import os
import requests
from requests.auth import HTTPDigestAuth

resp = requests.post(
    "https://apiv2.telecomsxchange.com/buyers/hlr/lookup/447700900123",
    auth=HTTPDigestAuth(os.environ["TCXC_USERNAME"], os.environ["TCXC_API_KEY"]),
    data={"i_account": 1501},
)
print(resp.json())

$ch = curl_init("https://apiv2.telecomsxchange.com/buyers/hlr/lookup/447700900123");
curl_setopt_array($ch, [
    CURLOPT_HTTPAUTH => CURLAUTH_DIGEST,
    CURLOPT_USERPWD => getenv('TCXC_USERNAME') . ':' . getenv('TCXC_API_KEY'),
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => http_build_query(['i_account' => 1501]),
    CURLOPT_RETURNTRANSFER => true,
]);
$response = json_decode(curl_exec($ch), true);

Response

{
  "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/sellers/hlr/lookup/{number}

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

numberstringpathRequired
Number in international format, digits only, with no + or leading zeros.
Example447700900123

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

POST/sellers/hlr/lookup/{number}

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

import os
import requests
from requests.auth import HTTPDigestAuth

resp = requests.post(
    "https://apiv2.telecomsxchange.com/sellers/hlr/lookup/447700900123",
    auth=HTTPDigestAuth(os.environ["TCXC_USERNAME"], os.environ["TCXC_API_KEY"]),
)
print(resp.json())

$ch = curl_init("https://apiv2.telecomsxchange.com/sellers/hlr/lookup/447700900123");
curl_setopt_array($ch, [
    CURLOPT_HTTPAUTH => CURLAUTH_DIGEST,
    CURLOPT_USERPWD => getenv('TCXC_USERNAME') . ':' . getenv('TCXC_API_KEY'),
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
]);
$response = json_decode(curl_exec($ch), true);

Response

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