Number Lookup / HLR API

Preview

REST

Response Fields

Authoritative reference for every field returned by single and bulk number lookups. Use this page when mapping HLR results into your database, rules engine, or CRM.

Identity Fields

msisdn, e164, country, and countryCode for storage and display consistency.

Network Fields

carrier, networkType, mcc, and mnc for routing and analytics.

Status Fields

ported, roaming, reachable, and hlrStatus for operational decisions.

Billing Fields

cost.amount and cost.currency on every successful enrichment row.

Core fields

14+

including nested cost

networkType

mobile | fixed | voip | unknown

hlrStatus

ACTIVE … UNKNOWN

Applies to

Both

single & bulk APIs

Authentication

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

Where these fields appear

Single lookup returns fields under data. Bulk lookup returns the same enrichment fields on each object in data.results[], plus bulk-only keys such as index, success, and summary.

Complete Result Object

Canonical shape of a successful enrichment. Nulls may appear for mcc / mnc when the network type is VoIP or the HLR cannot resolve codes.

JSON

{
  "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": "signup-user-42"
}

Identity & Geography

Field	Type	Required	Description
msisdn	string	required	The number exactly as submitted on the request (local, E.164 digits, or +prefixed). Use for debugging input; prefer e164 for storage.
e164	string	required	Normalized international number: country code + national significant number, digits only, no leading +. Example: 233244123456.
country	string	required	English country name derived from the resolved numbering plan (e.g. Ghana, Nigeria, Kenya).
countryCode	string	required	ISO 3166-1 alpha-2 country code (e.g. GH, NG, KE). Always uppercase in responses.

Storage recommendation

Persist e164 as the primary key for contacts. Keep msisdn only if you need to show the user what they typed. Display formatting (spaces, +) should be applied in the UI layer.

Carrier & Network

Field	Type	Required	Description
carrier	string	required	Human-readable current network/operator name (e.g. MTN, Telecel, AirtelTigo). For ported numbers this reflects the recipient network, not the original donor.
networkType	string	required	Classification of the line: mobile \| fixed \| voip \| unknown. See enum table below.
mcc	string \| null	optional	Mobile Country Code (ITU-T E.212), typically 3 digits as a string (e.g. "620"). Null when not applicable.
mnc	string \| null	optional	Mobile Network Code, 2–3 digits as a string (e.g. "01"). Combined with mcc uniquely identifies the PLMN.

networkType enum

Value	Meaning	Typical use
`mobile`	Mobile / cellular subscription	SMS, OTP, voice to handset
`fixed`	Landline or fixed wireless	Voice only; skip SMS OTP
`voip`	Internet telephony / virtual number	Higher fraud risk; optional block
`unknown`	Could not classify the line type	Conservative handling; optional re-lookup

Example MCC/MNC pairs (illustrative)

JSON

[
  { "carrier": "MTN Ghana", "mcc": "620", "mnc": "01" },
  { "carrier": "Telecel Ghana", "mcc": "620", "mnc": "02" },
  { "carrier": "AirtelTigo Ghana", "mcc": "620", "mnc": "03" }
]

Portability, Roaming & Reachability

Field	Type	Required	Description
ported	boolean	required	true if number portability data indicates the subscriber has moved from the originally allocated network to another operator.
roaming	boolean	required	true if the handset is registered on a visited network outside the home PLMN at query time.
reachable	boolean	required	true when HLR/network signals indicate the subscriber can currently receive traffic. false does not always mean permanently invalid.
hlrStatus	string	required	Normalized HLR status: ACTIVE \| ABSENT \| INACTIVE \| INVALID \| UNKNOWN. See table below.

hlrStatus enum

Value	Meaning	reachable?	Suggested action
`ACTIVE`	Allocated and known active	Usually true	Allow messaging / calls
`ABSENT`	Temporarily unavailable (off / no coverage)	Often false	Retry later; do not purge
`INACTIVE`	Deactivated or not in service	false	Suppress or re-collect number
`INVALID`	Not allocated / invalid at network	false	Remove permanently
`UNKNOWN`	No definitive HLR answer	May be false	Use secondary signals; optional retry

ported vs carrier

When ported is true, always trust carrier / mcc / mnc from this response for routing — not the original prefix-based operator mapping from national numbering plans.

Billing & Correlation

Field	Type	Required	Description
cost	object	required	Billing object for the successful lookup row. Absent on pure validation error rows in bulk errors[].
cost.amount	number	required	Decimal cost charged for this lookup (e.g. 0.008). Sum for bulk is data.totalCost.amount.
cost.currency	string	required	ISO 4217 currency code (typically USD for API pricing).
lookupId	string	optional	Present on single-lookup success (LKP-…). Bulk rows may omit this; use bulkId + index instead.
reference	string \| null	optional	Echo of your request reference when provided; null otherwise.

Response Envelope

Every API response is wrapped in a standard Sendexa envelope. Business data lives under data.

Field	Type	Required	Description
success	boolean	required	true when the request was accepted and processed (bulk may still include row errors).
code	string	required	Machine-readable status (LOOKUP_OK, BULK_LOOKUP_OK, BULK_LOOKUP_PARTIAL, INVALID_MSISDN, …).
message	string	required	Human-readable summary of the outcome.
requestId	string	required	Platform request ID (REQ-…). Include in support tickets.
timestamp	string	required	ISO 8601 UTC timestamp of the response.
data	object	optional	Payload for successful or partial responses. Omitted or null on hard failures.
errors	array	optional	Validation or row-level error objects (field/index, message, code).

Bulk-only Fields

Returned only by POST /v1/lookup/bulk.

Field	Type	Required	Description
bulkId	string	required	Identifier for the bulk operation (BLK-…).
total	number	required	Numbers submitted in the request.
succeeded	number	required	Rows with a successful HLR enrichment.
failed	number	required	Rows that failed validation or HLR.
summary	object	required	Aggregates across successful rows (reachable, ported, byNetworkType, byHlrStatus).
totalCost	object	required	Sum of row costs { amount, currency }.
results[].index	number	required	Zero-based index of the input numbers[] entry.
results[].success	boolean	required	Whether that row completed successfully.
errors[].index	number	required	Index of the failed input row.
errors[].code	string	required	Row error code (INVALID_MSISDN, LOOKUP_FAILED, …).

JSON

{
  "summary": {
    "reachable": 820,
    "unreachable": 120,
    "ported": 45,
    "roaming": 12,
    "byNetworkType": {
      "mobile": 900,
      "fixed": 20,
      "voip": 15,
      "unknown": 5
    },
    "byHlrStatus": {
      "ACTIVE": 850,
      "ABSENT": 40,
      "INACTIVE": 30,
      "INVALID": 20,
      "UNKNOWN": 0
    }
  }
}

TypeScript Types

TypeScript

interface LookupCost {
  amount: number;
  currency: string;
}

type NetworkType = "mobile" | "fixed" | "voip" | "unknown";

type HlrStatus =
  | "ACTIVE"
  | "ABSENT"
  | "INACTIVE"
  | "INVALID"
  | "UNKNOWN";

interface LookupResult {
  lookupId?: string;
  msisdn: string;
  e164: string;
  country: string;
  countryCode: string;
  carrier: string;
  networkType: NetworkType;
  ported: boolean;
  roaming: boolean;
  reachable: boolean;
  hlrStatus: HlrStatus;
  mcc: string | null;
  mnc: string | null;
  cost: LookupCost;
  reference?: string | null;
}

Decision Mapping Examples

Allow OTP / SMS

JavaScript

reachable === true
&& hlrStatus === 'ACTIVE'
&& networkType === 'mobile'

Step-up fraud review

JavaScript

networkType === 'voip'
|| hlrStatus === 'UNKNOWN'
|| (ported === true && roaming === true)

Route by PLMN

JavaScript

// Prefer mcc+mnc over prefix tables
const plmn = `${mcc}${mnc}`;
routeSms(e164, plmn, carrier);

Suppress permanently

JavaScript

hlrStatus === 'INVALID'
|| (hlrStatus === 'INACTIVE'
    && reachable === false)

Nullability & Edge Cases

Situation	Field impact
VoIP or non-cellular line	networkType may be voip; mcc/mnc often null; carrier may be generic
Temporary network outage on handset	hlrStatus ABSENT; reachable false; still billable success
Number never allocated	hlrStatus INVALID; reachable false; do not message
Ported mobile number	ported true; carrier/mcc/mnc reflect recipient network
International roaming	roaming true; home carrier still returned when available
Bulk validation error row	Row appears only in errors[]; no cost; no HLR fields

Related endpoints

POST /v1/lookup — single number enrichment
POST /v1/lookup/bulk — batch enrichment (max 1000)
Getting Started — auth and first request