Understanding the response

Every successful lookup returns JSON. Three fields do most of the work — here's the shape of a response and where to look.

{
  "body": {
    "results": [
      {
        "error": "NONE",
        "uuid": "4562ab7e-af26-4d42-87a0-b84bb4e5f96c",
        "credits_spent": 1,
        "detected_telephone_number": "447540822872",
        "live_status": "LIVE",                 // ← is it active & reachable?
        "telephone_number_type": "MOBILE",     // ← mobile, landline, VoIP…
        "current_network_details": {           // ← which network, right now
          "name": "EE Limited (T-Mobile)",
          "mccmnc": "23430",
          "country_iso3": "GBR"
        },
        "is_ported": "YES",
        "timestamp": "2022-10-07T13:06:15Z"
      }
    ]
  }
}

The three fields most customers use

live_status — is this number active and reachable? Most business logic hangs off this one field.

telephone_number_type — mobile, landline, VoIP, premium and more. Use it to route calls or exclude non-SMS numbers.

current_network_details — the network the number is on today, including after porting. Useful for routing and least-cost decisions.

Two rules that will save you an integration headache

1. JSON is unordered. Never rely on fields appearing in the same order — parse by field name.

2. We add fields, we never change them. New features arrive as new response fields, so upgrades never break your integration. Anything that costs extra is opt-in (like get_ported_date) — you must ask for it in your request.

Matching responses to requests

Sending multiple numbers in one request? Use request_parameters.telephone_number in each result to match it back to what you submitted. Every result also carries a unique uuid.

Full field-by-field reference →

live_status values

live_status tells you whether a phone number is real, active and reachable right now. It's always an UPPERCASE string — match it exactly.

telephone_number_type values

What kind of number is it? Use this field to route calls, exclude non-SMS numbers, or spot premium-rate traps. The example numbers are real test values — use them to test your handling of each type.

All response fields

Every field in a lookup result, in one searchable table.

Errors & HTTP codes

Two layers: HTTP status codes on the whole request, and an error field on each individual result.

HTTP status codes

The error field (per result)

Rate limits at a glance

You're limited to 210 concurrent requests. Don't wait for a response before sending the next request — fire in parallel. If a slow network takes 10 seconds per lookup, 20 requests/second still gives you a steady throughput of 20/second after the initial lag.

Number formatting — input

Use the input_format parameter to submit locally-formatted numbers without converting them to E.164 yourself.

How it works

By default the API expects international E.164 format (digits only, no leading +). If you pass a local number like 07790606023 without an input_format, the API can't identify which country it belongs to and returns BAD_FORMAT.

Add "input_format": "GBR" (a 3-letter ISO country code) to your request and the API will prepend the correct country code automatically before processing.

Examples

Request example

curl -H "Content-Type: application/json" -X POST \
  -d '{"api_key":"your_api_key","api_secret":"your_api_secret",
       "requests":[{"telephone_number":"07790606023","input_format":"GBR"}]}' \
  https://api.hlrlookup.com/apiv2/hlr

Number formatting — output

Use the output_format parameter to get the detected number back in a consistent format for your database or downstream system.

Available formats

Request example

curl -H "Content-Type: application/json" -X POST \
  -d '{"api_key":"your_api_key","api_secret":"your_api_secret",
       "requests":[{"telephone_number":"447790606023","output_format":"PLUS_E164"}]}' \
  https://api.hlrlookup.com/apiv2/hlr

The formatted number appears in the formatted_telephone_number field of the response.

Cache system

The cache stores lookup results for up to 30 days, reducing latency and saving credits on repeated checks of the same number.

Two cache levels

Private cache — results from your own account's previous lookups. Retrieving from your private cache is free.

Global cache — results from other accounts that chose to share their results. Costs ½ credit per lookup.

How the cache is checked

1. If cache_days_private is set, the private cache is checked first. A match is returned free.
2. If no private match, and cache_days_global is set, the global cache is checked. A match costs ½ credit.
3. If no cached result exists, a live network lookup is performed.

Cache parameters

Request example

curl -H "Content-Type: application/json" -X POST \
  -d '{"api_key":"your_api_key","api_secret":"your_api_secret",
       "requests":[{"telephone_number":"441133910781",
                    "cache_days_private":30,
                    "cache_days_global":15,
                    "save_to_cache":"YES"}]}' \
  https://api.hlrlookup.com/apiv2/hlr

Ported date feature

Retrieve the date a number was last ported to a different network. Useful for detecting port-out fraud and verifying recent number history.

Why it matters

Port-out fraud is a scheme where criminals hijack a phone number by transferring it to a new network in order to intercept one-time passwords for banking and email accounts. Knowing when a number was last ported lets you flag suspicious recent activity.

Limitations

If a number was ported away from its original network and then ported back, the last ported date cannot be retrieved.

The cache is automatically disabled when get_ported_date: YES is set, since the feature is specifically designed to catch numbers that have been recently ported.

Pricing

Coverage

65 countries, listed below with the date each was added. Most were added July 2020; a batch of newer countries (India, Bangladesh, Nigeria, Iran, Jamaica, Georgia and others) was added July 2025. Check the Coverage Checker for the latest.

Request example

curl -H "Content-Type: application/json" -X POST \
  -d '{"api_key":"your_api_key","api_secret":"your_api_secret",
       "requests":[{"telephone_number":"447540822872","get_ported_date":"YES"}]}' \
  https://api.hlrlookup.com/apiv2/hlr

The response includes a ported_date field with an ISO 8601 date, NOT_AVAILABLE, or NOT_APPLICABLE.

Landline status feature

Check whether a UK or Irish landline number is live, dead, or has a more specific status such as out-of-order or call-barred.

Coverage

Currently available for:

• United Kingdom (GBR) — available since January 2020
• Ireland (IRL) — available since July 2021

Pricing

There is a 1 credit surcharge for landline status checks, bringing the total to 2 credits when the number is a landline in coverage.

How it works

The result is mapped into the standard live_status field (LIVE / DEAD / INCONCLUSIVE) and an additional landline_status field with the raw, more granular status the network returned. Every raw value falls into one of three buckets — the table below is the complete mapping, so any raw value you see can be looked up here:

Request example

curl -H "Content-Type: application/json" -X POST \
  -d '{"api_key":"your_api_key","api_secret":"your_api_secret",
       "requests":[{"telephone_number":"441133910781","get_landline_status":"YES"}]}' \
  https://api.hlrlookup.com/apiv2/hlr

USA status feature

Check the live status of US mobile numbers. Standard HLR lookups return NOT_AVAILABLE_NETWORK_ONLY for US numbers — this feature provides actual live/dead status.

Coverage limitations

The feature supports US mobile numbers only. The following US territories are not covered:

• Puerto Rico
• Guam
• US Virgin Islands

Non-mobile US numbers return NOT_AVAILABLE_NETWORK_ONLY even with this feature enabled.

Pricing

Request example

curl -H "Content-Type: application/json" -X POST \
  -d '{"api_key":"your_api_key","api_secret":"your_api_secret",
       "requests":[{"telephone_number":"17148307000","usa_status":"YES"}]}' \
  https://api.hlrlookup.com/apiv2/hlr

The response includes a usa_status field indicating that this optional feature was used.

Bulk uploads via API

Submit large lists of numbers via the batch API — upload a CSV, monitor progress, pause and resume, then download results.

Upload methods

Two approaches are supported:

1. CSV file upload — upload a locally-stored CSV file.
2. JSON body — submit numbers directly in the request body. Limited to 100,000 numbers or 2 MB.

If your CSV has multiple columns (e.g. your own reference ID alongside the number), tell us which column holds the phone numbers by adding &column= to the upload URL:

Omitting &column= always checks the first column. Example — numbers in column B: .../source?apikey=your_api_key&secret=your_api_secret&column=1

Batch operations

Optional parameters

Batch creation accepts the same optional parameters as single lookups: cache_days_private, cache_days_global, save_to_cache, output_format, input_format, get_ported_date, get_landline_status, and usa_status. Include them inside a batchArguments object when you create the batch.

Downloading results

Completed batches can be downloaded as CSV or JSON. Results include live_status, telephone_number_type, original_network, is_ported, and all other standard response fields.

Common errors

Testing suite

Test your integration for free without touching a real phone network. The testing endpoint returns pre-populated responses that simulate every status and error.

Test credentials

Endpoint:    https://testing.hlrlookup.com/apiv2/hlr
api_key:     speedtest
api_secret:  speedtest

How it works

The testing suite is not connected to the telephone network. It contains a dataset of pre-populated example responses. Submit any number and it returns the closest match from the dataset — it won't return an exact match for every number.

Simulating 429 errors

The testing suite simulates rate limiting. Submit more than 200 requests per second to trigger 429 responses. Afghanistan numbers (country code 93) trigger 429 responses at lower rates to simulate congested network conditions — and also return slower response times.

If you know in advance which network a number is on, you can reduce requests to just that network rather than slowing down overall. Ask your account manager about our e164 validation service — it detects a number's network without performing a full HLR lookup.

Sample test numbers

This is a small sample — a longer list is available on request from support@hlrlookup.com. You can also submit any number not in this list; you'll get back the closest match from the test dataset rather than an error.

Charging

Credits are only spent on HTTP 200 responses. Errors (400, 401, 429, 500, 404) are always free. See the pricing page for the per-credit cost.

Always free

• HTTP 400, 401, 429, 500, 404 responses
• error: INSUFFICIENT_CREDIT or error: INTERNAL_ERROR results
• telephone_number_type: BAD_FORMAT
• Non-mobile numbers with live_status: NO_COVERAGE

Base charges (HLR — no optional features)

Optional features (additional charges)

MNP endpoint

MNP lookups cost half the HLR rate. Base charge: ½ credit live, ¼ credit from global cache. With ported date: ½–1½ credits. Ported dates are never cached on MNP lookups.

Request parameters

All parameters you can send in a lookup request, including authentication, per-number options, and optional features.

Endpoints

Checking your balance

Check your remaining credits at any time — just your api_key and api_secret, no other parameters needed:

curl -s -H "Content-Type: application/json" -X POST \
  -d '{"api_key":"your_api_key","api_secret":"your_api_secret"}' \
  https://api.hlrlookup.com/apiv2/balance

{
  "body": {
    "Status": "OK",
    "Credits": 15000
  }
}

Authentication (required)

Optional parameters (per number)

HTTP POST format

The API accepts requests in JSON (recommended) or form-encoded format. JSON supports batch requests; form-encoded is single numbers only.

JSON format

Set Content-Type: application/json and POST a JSON body.

Single number

{
  "api_key": "your_api_key_here",
  "api_secret": "your_api_secret_here",
  "requests": [
    { "telephone_number": "447540822872" }
  ]
}

Single number with parameters

{
  "api_key": "your_api_key_here",
  "api_secret": "your_api_secret_here",
  "requests": [
    {
      "telephone_number": "447540822872",
      "cache_days_private": 30,
      "output_format": "PLUS_E164",
      "save_to_cache": "YES"
    }
  ]
}

Multiple numbers

{
  "api_key": "your_api_key_here",
  "api_secret": "your_api_secret_here",
  "requests": [
    { "telephone_number": "447540822872", "cache_days_private": 30 },
    { "telephone_number": "441133910781", "output_format": "E164" },
    { "telephone_number": "07790606023",  "input_format": "GBR" }
  ]
}

Form-encoded format

Set Content-Type: application/x-www-form-urlencoded. Single numbers only — batching is not supported.

curl -X POST \
  -d "api_key=your_api_key&api_secret=your_api_secret&telephone_number=447540822872&cache_days_private=8&output_format=PLUS_E164&save_to_cache=YES" \
  https://api.hlrlookup.com/apiv2/hlr

Optional HTTP headers

Example requests & responses

Working examples of common lookup scenarios — single number, multiple numbers, optional features, and error responses.

Single number lookup

curl -H "Content-Type: application/json" -X POST \
  -d '{"api_key":"your_api_key","api_secret":"your_api_secret",
       "requests":[{"telephone_number":"447540822872"}]}' \
  https://api.hlrlookup.com/apiv2/hlr

{
  "body": {
    "results": [{
      "error": "NONE",
      "uuid": "4562ab7e-af26-4d42-87a0-b84bb4e5f96c",
      "credits_spent": 1,
      "detected_telephone_number": "447540822872",
      "live_status": "LIVE",
      "telephone_number_type": "MOBILE",
      "original_network": "AVAILABLE",
      "original_network_details": {
        "name": "O2 (UK)", "mccmnc": "23410",
        "country_name": "United Kingdom", "country_iso3": "GBR",
        "area": "United Kingdom", "country_prefix": "44"
      },
      "current_network": "AVAILABLE",
      "current_network_details": {
        "name": "EE Limited (T-Mobile)", "mccmnc": "23430",
        "country_name": "United Kingdom", "country_iso3": "GBR",
        "country_prefix": "44"
      },
      "is_ported": "YES",
      "timestamp": "2022-10-07T13:06:15Z"
    }]
  }
}

With optional parameters

Adding get_ported_date: YES and output_format: PLUS_E164:

{
  "error": "NONE",
  "credits_spent": 1,
  "detected_telephone_number": "447540822872",
  "formatted_telephone_number": "+447540822872",
  "live_status": "LIVE",
  "is_ported": "YES",
  "ported_date": "NOT_AVAILABLE",
  "timestamp": "2022-10-07T13:06:15Z"
}

Only 1 credit here — the ported date feature is charged at 1 credit when requested but not available, and 2 credits only when a date is actually returned.

Multiple numbers

Each number in the requests array gets its own result in the same position. Use request_parameters.telephone_number to match results back to your inputs.

Error responses

MCP Server

Give AI tools and coding agents — like Claude Code — direct access to HLR Lookup through the Model Context Protocol (MCP). No custom integration code required.

Server details

Available tools

The server exposes four tools:

hlr_lookup

Performs a live HLR lookup for up to 80 telephone numbers in a single request. The response can include telephone_number_type, live_status, original network, current network, mobile number portability information, and the sms_email/mms_email gateway addresses.

Optional additional fields: ported_date, landline_status, usa_status. Requesting usa_status performs an extra live US status check and consumes an additional credit.

mnp_lookup

Same general request and response structure as hlr_lookup.

validate

Checks formatting and network information without performing a live HLR lookup — useful for pre-flight checks before spending credits on a real lookup. Free — consumes no credits.

balance

Returns the remaining credit balance for the authenticated account. Free — consumes no credits.

Authentication

Every tool call needs authentication — including validate and balance, which don't consume credits. "Free" means zero credits, not no login: you still need a valid API key and secret. Only MCP schema discovery works without authentication.

Send credentials as a Bearer token in the Authorization header:

Authorization: Bearer <api_key>:<api_secret>

Manage your API credentials in the HLR Lookup portal.

Shared lookup options

All lookup tools (hlr_lookup, mnp_lookup, validate) share the same input, output and cache options.

Input format

Submit numbers in national or E.164 format. For national format, add input_format with the relevant ISO 3166-1 alpha-3 country code — e.g. GBR.

Output format

Cache controls

Error handling

Authentication and request errors come back as valid MCP error responses with isError: true. The structured content includes a link to the account settings page, the expected Authorization header format, and an explanation that valid credentials are required.

Connecting with Claude Code

Add the server with:

claude mcp add --transport http hlrlookup https://api.hlrlookup.com/mcp \
  --header "Authorization: Bearer <api_key>:<api_secret>"

Replace <api_key> and <api_secret> with your own credentials. Once added, Claude Code can discover and call the available HLR Lookup tools directly.