SendexaDocs
Dash
Number Lookup / HLR API
Preview
REST

Lookup Number

Look up a single phone number and receive live HLR data: carrier, network type, MCC/MNC, portability, roaming, reachability, and billing cost.

Synchronous HLR

One request returns a complete enrichment payload — no polling or job ID required for single lookups.

Auto Normalization

Local and international inputs are normalized to E.164 with country metadata in the response.

Port & Roam Aware

Detect number portability and roaming so routing and fraud rules stay accurate.

Billable Clarity

Each success includes cost.amount and currency so you can reconcile spend per lookup.

Avg Response

<400ms

95th percentile

Typical Cost

$0.008

per successful lookup

Rate Limit

50/s

per API key

Timeout

30s

client recommendation

POST
/v1/lookup
Core
Preview

Endpoint

Base URL: https://api.sendexa.co

Bash
POST https://api.sendexa.co/v1/lookup
Content-Type: application/json
Authorization: Basic YOUR_DASHBOARD_TOKEN

Request Body

application/json
JSON
{
  "msisdn": "0244123456",
  "countryCode": "GH"
}
FieldTypeRequiredDescription
msisdnstring
required
Phone number in local or international format. Digits preferred; leading + is accepted.
countryCodestringoptionalISO 3166-1 alpha-2 country (e.g. GH). Required for reliable national-format parsing.
referencestringoptionalYour correlation ID (max 64 chars). Echoed in the response when provided.

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"
    },
    "reference": null
  }
}

Response Fields

High-level map of data. See the full field reference for enums and edge cases.

FieldTypeRequiredDescription
lookupIdstring
required
Unique ID for this lookup (LKP-…). Store for support and audits.
msisdnstring
required
Original number as submitted in the request.
e164string
required
Normalized international number (digits only, no +).
countrystring
required
Human-readable country name (e.g. Ghana).
countryCodestring
required
ISO 3166-1 alpha-2 code (e.g. GH).
carrierstring
required
Current serving or home carrier name (e.g. MTN, Vodafone).
networkTypestring
required
One of: mobile | fixed | voip | unknown.
portedboolean
required
True if the number has been ported from its original network.
roamingboolean
required
True if the subscriber is currently roaming.
reachableboolean
required
True when the network reports the subscriber as reachable.
hlrStatusstring
required
ACTIVE | ABSENT | INACTIVE | INVALID | UNKNOWN.
mccstring
required
Mobile Country Code (e.g. 620 for Ghana).
mncstring
required
Mobile Network Code (e.g. 01 for MTN Ghana).
costobject
required
{ amount: number, currency: string } billed for this lookup.

Code Examples

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",
    "reference": "signup-user-42"
  }'

HTTP Status Codes

CodeStatusDescription
200OKLookup completed; data contains HLR results
400Bad RequestInvalid msisdn, countryCode, or body schema
401UnauthorizedMissing or invalid Basic Auth token
403ForbiddenInsufficient credits or product not enabled
422UnprocessableUpstream HLR failure (LOOKUP_FAILED)
429Too Many RequestsRate limit exceeded (50 requests/second)
500Server ErrorUnexpected platform error — retry with backoff

API Error Codes

CodeHTTPCause
INVALID_MSISDN400msisdn missing, empty, or unparseable
INVALID_COUNTRY_CODE400countryCode not a valid ISO alpha-2 value
UNAUTHORIZED401Bad or missing Authorization header
INSUFFICIENT_CREDITS403Balance too low for this lookup
LOOKUP_FAILED422HLR provider timeout or temporary failure
RATE_LIMIT_EXCEEDED429Exceeded 50 requests per second

Common Use Cases

OTP

Pre-OTP number check

Confirm reachable and networkType before sending a verification code.

Routing

Carrier selection

Use ported, mcc, and mnc to pick the correct SMS or voice route.

Fraud

Signup risk filter

Block or step-up auth when networkType is voip or status is INVALID.