Number Lookup / HLR API

Preview

REST

Getting Started

Set up authentication, understand number formats, run your first single lookup, then move on to bulk validation and field-level handling in your application.

Dashboard Token

Copy your pre-computed Base64 token from Settings → API Keys — no manual Base64 encoding required.

Flexible Numbers

Send local format with countryCode, or pass E.164 directly. We normalize to e164 in every response.

First Lookup Fast

A single POST to /v1/lookup returns carrier, reachability, and HLR status in under a second.

Safe Defaults

Invalid numbers fail validation before HLR is billed. Insufficient credits are rejected clearly.

Base URL

api.sendexa.co

HTTPS only

Auth

Basic

Dashboard token

Content-Type

JSON

application/json

First call

<1 min

with a valid token

Authentication

All REST requests use HTTP Basic Auth with your dashboard Base64 token: Authorization: Basic <token>. Auth guide →

Prerequisites

Sendexa business account

API token from the dashboard

Open Settings → API Keys and copy the pre-computed Base64 token. Use it as Authorization: Basic YOUR_DASHBOARD_TOKEN.

Positive credit balance

Lookups are billed per successful HLR query. Top up credits before running bulk jobs.

Authentication

Every request to the Number Lookup API must include an HTTP Basic Authorization header. The token is already Base64-encoded in the dashboard — paste it as-is after the word Basic.

Bash

# Header format
Authorization: Basic YOUR_DASHBOARD_TOKEN

# Example request
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"}'

Do not re-encode the token

The dashboard value is already Base64. Encoding it again will cause HTTP 401 UNAUTHORIZED. Never commit tokens to source control — use environment variables.

Full authentication details: Authentication guide →

Number Formats

You can submit numbers in local national format or international E.164. Always include countryCode when the number is not already in full international form so normalization is unambiguous.

Field	Type	Required	Description
msisdn	string	required	Phone number to look up. Local (0244123456) or international (233244123456 / +233244123456).
countryCode	string	optional	ISO 3166-1 alpha-2 country (e.g. GH, NG, KE). Strongly recommended for local-format numbers.

JSON

{
  "msisdn": "0244123456",
  "countryCode": "GH"
}

Normalized output

Regardless of input format, successful lookups always return e164 (digits only, country code included, no +) plus the original msisdn you submitted. Use e164 as your canonical stored number.

Your First Lookup

Call POST https://api.sendexa.co/v1/lookup with a JSON body. A successful response returns HTTP 200 and a data object with carrier, network type, HLR status, and cost.

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

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

Using Results in Your App

Map lookup fields to product decisions. The table below shows common rules teams apply after a successful response.

Condition	Suggested action
hlrStatus === "ACTIVE" && reachable === true	Allow OTP / SMS / voice; treat as high-confidence mobile
networkType === "voip"	Increase fraud scrutiny or block high-risk flows
ported === true	Route using current carrier/MCC-MNC, not original allocation
roaming === true	Expect higher latency or delivery cost; optional delay
hlrStatus === "INVALID" \|\| reachable === false	Do not send; ask user for another number

Handling Errors

Error responses share a consistent envelope. Always check success and branch on code.

JSON

{
  "success": false,
  "code": "INVALID_MSISDN",
  "message": "The phone number could not be parsed or is empty.",
  "requestId": "REQ-1782001999888",
  "timestamp": "2026-07-12T10:16:01.002Z",
  "errors": [
    {
      "field": "msisdn",
      "message": "msisdn is required and must contain at least 7 digits"
    }
  ]
}

HTTP	Code	What to do
400	`INVALID_MSISDN`	Validate client-side; fix format before retry
401	`UNAUTHORIZED`	Check token and Authorization header spelling
403	`INSUFFICIENT_CREDITS`	Top up balance; stop bulk jobs until funded
429	`RATE_LIMIT_EXCEEDED`	Backoff and retry; prefer bulk for large lists

Next Steps

Single Lookup

Full request/response schema, validation rules, and code samples for POST /v1/lookup.

Open docs

Bulk Lookup

Clean up to 1,000 numbers per request with per-row results and aggregate summaries.

Open docs

Field Reference

Definitions for every response field including enums for networkType and hlrStatus.

Open docs

Checklist before going live

Store the dashboard token in a secrets manager or env var
Log requestId and lookupId on every call
Handle 400 / 401 / 403 / 429 / 422 explicitly in your client
Prefer bulk for lists larger than ~20 numbers
Read Response Fields before mapping results into your database schema