SendexaDocs
Dash
Number Lookup / HLR API
Preview
REST

Number Lookup / HLR API

Query live Home Location Register (HLR) data for any phone number. Resolve carrier, network type, portability, roaming, and reachability before you send SMS, place calls, or onboard users.

Live HLR Queries

Real-time Home Location Register lookups return current carrier, MCC/MNC, and subscriber status from the network.

Carrier & Type Detection

Identify mobile, fixed, VoIP, or unknown network types with the serving carrier name and country context.

Portability Aware

Detect ported numbers so you route SMS, voice, and OTP traffic to the correct destination network.

Roaming & Reachability

Know whether a handset is roaming and whether the number is currently reachable before you send.

Bulk Validation

Clean up to 1,000 numbers per request — ideal for list hygiene, campaign prep, and fraud screening.

Credit-Safe Billing

Every response includes the lookup cost so you can track spend and only pay for successful HLR queries.

Avg Latency

<400ms

Single lookup P95

Bulk Limit

1,000

numbers per request

Rate Limit

50/s

per API key

Coverage

Global

MNO & MVNO networks

Quick Start

Look up a single number in one request. Use your dashboard Base64 token with HTTP Basic Auth.

Bash
curl -X POST 'https://api.sendexa.co/v1/lookup' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic YOUR_DASHBOARD_TOKEN' \
  -d '{
    "msisdn": "0244123456",
    "countryCode": "GH"
  }'

Success response

JSON
{
  "success": true,
  "code": "LOOKUP_OK",
  "message": "Number lookup completed successfully.",
  "requestId": "REQ-1782001122334",
  "timestamp": "2026-07-12T10:15:22.104Z",
  "data": {
    "lookupId": "LKP-9f3a2c1b-4e8d-4a71-b2c0-1d9e8f7a6b5c",
    "msisdn": "0244123456",
    "e164": "233244123456",
    "country": "Ghana",
    "countryCode": "GH",
    "carrier": "MTN",
    "networkType": "mobile",
    "ported": false,
    "roaming": false,
    "reachable": true,
    "hlrStatus": "ACTIVE",
    "mcc": "620",
    "mnc": "01",
    "cost": {
      "amount": 0.008,
      "currency": "USD"
    }
  }
}
What You Get From a Lookup
Identity

Normalized e164, original msisdn, country, and ISO countryCode for consistent storage and routing.

Network

carrier, networkType (mobile | fixed | voip | unknown), mcc, mnc, and ported status.

Status

hlrStatus, reachable, roaming, and per-lookup cost for operational decisions and billing reconciliation.

Full field definitions, enums, and examples are on the Response Fields page.

HLR Status Values
hlrStatusMeaningTypical action
ACTIVENumber is allocated and known active on the networkSafe to message or call
ABSENTSubscriber temporarily not available (handset off/out of coverage)Retry later; do not permanently drop
INACTIVENumber not currently active or deactivatedFlag for re-verification or suppress
INVALIDNumber not allocated or format invalid at network layerRemove from lists; do not send
UNKNOWNHLR could not return a definitive statusUse with other signals; optional retry
Common Error Codes
HTTPCodeCause
400INVALID_MSISDNPhone number missing, empty, or not parseable
400INVALID_COUNTRY_CODEcountryCode is not a valid ISO 3166-1 alpha-2 value
400BULK_LIMIT_EXCEEDEDBulk request contains more than 1,000 numbers
401UNAUTHORIZEDMissing or invalid Authorization header
403INSUFFICIENT_CREDITSAccount balance too low for the lookup(s)
422LOOKUP_FAILEDUpstream HLR provider could not complete the query
429RATE_LIMIT_EXCEEDEDExceeded 50 req/s — implement exponential backoff
Common Use Cases
List hygiene

Clean contact databases

Drop invalid and inactive numbers before SMS or voice campaigns to cut cost and improve deliverability.

Routing

Carrier-aware routing

Use ported and MCC/MNC data to select the best SMS or voice route and avoid wrong-network fees.

Fraud & KYC

Onboarding checks

Reject VoIP or unreachable numbers during signup, OTP, or payment flows before costly verification steps.