{ "openapi": "3.1.0", "info": { "title": "HLR Lookup API v2", "version": "2.0.0", "summary": "Real-time HLR, MNP, number validation and balance enquiry endpoints.", "description": "Machine-readable description of the HLR Lookup API v2.\n\nAll endpoints are `POST` with a JSON body. Every request must include an `api_key` and `api_secret` pair.\n\nLookup endpoints (`/apiv2/hlr`, `/apiv2/mnp`, `/apiv2/validate`) accept either:\n\n- a **flat** body describing a single number (e.g. `{ \"api_key\": \"…\", \"api_secret\": \"…\", \"telephone_number\": \"447790606023\" }`), or\n- a **nested** body with up to 80 items in a `requests` array.\n\nThe flat form is internally rewritten to a single-item nested request, so the response shape is always `{ \"results\": [ … ] }`.\n\nSee https://www.hlrlookup.com/knowledge for prose documentation.", "contact": { "name": "HLR Lookup support", "url": "https://www.hlrlookup.com/contact" }, "license": { "name": "Proprietary", "url": "https://www.hlrlookup.com/terms" } }, "servers": [ { "url": "https://api.hlrlookup.com", "description": "Production" } ], "tags": [ { "name": "Lookup", "description": "Live network lookups that may consume credits." }, { "name": "Account", "description": "Account-level queries that do not consume credits." } ], "security": [], "paths": { "/apiv2/hlr": { "post": { "tags": ["Lookup"], "summary": "Full HLR lookup", "description": "Performs a live HLR lookup: returns number type, live status, original and current network (including MNP/porting information), SMS/MMS email gateways and optional extras such as ported date, landline status and IMSI hash.", "operationId": "hlrLookup", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LookupRequest" }, "examples": { "flat": { "summary": "Flat single-number request", "value": { "api_key": "YOUR_API_KEY", "api_secret": "YOUR_API_SECRET", "telephone_number": "447790606023", "output_format": "PLUS_E164", "cache_days_global": 7, "cache_days_private": 30, "save_to_cache": "YES" } }, "nested": { "summary": "Nested batch request", "value": { "api_key": "YOUR_API_KEY", "api_secret": "YOUR_API_SECRET", "requests": [ { "telephone_number": "447790606023", "output_format": "PLUS_E164" }, { "telephone_number": "16175551212", "usa_status": "YES" } ] } } } } } }, "responses": { "200": { "description": "Results array. Individual items may be success or per-request error objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HlrResponse" }, "examples": { "success": { "summary": "Successful lookup", "value": { "results": [ { "error": "NONE", "uuid": "6f1b8b3e-9a5e-4c7b-9a37-3e1d2b8e0a11", "request_parameters": { "telephone_number": "447790606023", "input_format": "", "output_format": "PLUS_E164", "save_to_cache": "YES", "cache_days_global": 7, "cache_days_private": 30, "get_ported_date": "NO", "get_landline_status": "NO", "usa_status": "NO" }, "credits_spent": 1, "detected_telephone_number": "447790606023", "formatted_telephone_number": "+447790606023", "telephone_number_type": "MOBILE", "live_status": "LIVE", "original_network": "AVAILABLE", "original_network_details": { "name": "Vodafone", "mccmnc": "23415", "country_name": "United Kingdom", "country_iso3": "GBR", "area": "", "country_prefix": "44" }, "current_network": "AVAILABLE", "current_network_details": { "name": "EE", "mccmnc": "23430", "country_name": "United Kingdom", "country_iso3": "GBR", "country_prefix": "44" }, "is_ported": "YES", "sms_email": "", "mms_email": "", "timestamp": "2026-04-21T09:15:02Z" } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/apiv2/mnp": { "post": { "tags": ["Lookup"], "summary": "MNP-only lookup", "description": "Mobile Number Portability lookup. Shape matches `/apiv2/hlr` except that for country code 1 (NANP) the `telephone_number_type` field is omitted from each result.", "operationId": "mnpLookup", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LookupRequest" }, "examples": { "nanp": { "summary": "US number (telephone_number_type omitted in response)", "value": { "api_key": "YOUR_API_KEY", "api_secret": "YOUR_API_SECRET", "telephone_number": "16175551212", "output_format": "NATIONAL" } } } } } }, "responses": { "200": { "description": "MNP results array.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HlrResponse" }, "examples": { "nanp": { "summary": "US response omits telephone_number_type", "value": { "results": [ { "error": "NONE", "uuid": "2f57a2f9-f0b1-4f2a-9a44-b1a0df2d6b44", "request_parameters": { "telephone_number": "16175551212", "input_format": "", "output_format": "NATIONAL", "save_to_cache": "PRIVATE", "cache_days_global": 0, "cache_days_private": 7, "get_ported_date": "NO", "get_landline_status": "NO", "usa_status": "NO" }, "credits_spent": 1, "detected_telephone_number": "16175551212", "formatted_telephone_number": "(617) 555-1212", "live_status": "NOT_AVAILABLE_NETWORK_ONLY", "original_network": "AVAILABLE", "original_network_details": { "name": "New England Telephone", "mccmnc": "", "country_name": "United States", "country_iso3": "USA", "area": "Boston, MA", "country_prefix": "1" }, "current_network": "AVAILABLE", "current_network_details": { "name": "Verizon Wireless", "mccmnc": "311480", "country_name": "United States", "country_iso3": "USA", "country_prefix": "1" }, "is_ported": "UNKNOWN", "sms_email": "", "mms_email": "", "timestamp": "2026-04-21T09:16:47Z" } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/apiv2/validate": { "post": { "tags": ["Lookup"], "summary": "Format-only validation", "description": "Validates the supplied number(s) and returns number type, network issuing details and formatted output without performing a live HLR lookup. The response is a subset of `/apiv2/hlr`: `live_status`, `current_network`, `current_network_details`, `is_ported`, `ported_date`, `landline_status`, `sms_email`, `mms_email` and all cache-related fields are omitted.", "operationId": "validate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LookupRequest" }, "examples": { "simple": { "summary": "Single-number validate", "value": { "api_key": "YOUR_API_KEY", "api_secret": "YOUR_API_SECRET", "telephone_number": "447790606023", "output_format": "E164" } } } } } }, "responses": { "200": { "description": "Validation results array.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateResponse" }, "examples": { "success": { "summary": "Successful validate", "value": { "results": [ { "error": "NONE", "uuid": "d8c15b2a-5b9b-4e3d-97e9-4a4f8b1b0cb5", "request_parameters": { "telephone_number": "447790606023", "input_format": "", "output_format": "E164" }, "credits_spent": 0, "detected_telephone_number": "447790606023", "formatted_telephone_number": "447790606023", "telephone_number_type": "MOBILE", "original_network": "AVAILABLE", "original_network_details": { "name": "Vodafone", "mccmnc": "23415", "country_name": "United Kingdom", "country_iso3": "GBR", "area": "", "country_prefix": "44" }, "timestamp": "2026-04-21T09:17:10Z" } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/apiv2/balance": { "post": { "tags": ["Account"], "summary": "Account credit balance", "description": "Returns the account's remaining credit balance. Accepts credentials only (`api_key` + `api_secret`).", "operationId": "balance", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceRequest" }, "examples": { "apiKey": { "summary": "API key credentials", "value": { "api_key": "YOUR_API_KEY", "api_secret": "YOUR_API_SECRET" } } } } } }, "responses": { "200": { "description": "Current balance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceResponse" }, "examples": { "ok": { "summary": "Balance OK", "value": { "Status": "OK", "Credits": 1234.5 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } } }, "components": { "schemas": { "YesNo": { "type": "string", "enum": ["YES", "NO"] }, "RequestItem": { "title": "RequestItem", "type": "object", "description": "A single number to look up. Only `telephone_number` is required.", "required": ["telephone_number"], "additionalProperties": false, "properties": { "telephone_number": { "type": "string", "description": "Phone number in international E.164 (digits only, no leading `+`) or national format (in which case `input_format` must be set to the ISO3 country code)." }, "input_format": { "type": "string", "description": "Empty string (default) for international input, or an ISO3 country code when `telephone_number` is in national format." }, "output_format": { "type": "string", "description": "Format of `formatted_telephone_number` in the response. One of the literals below, or a valid ISO3 country code to format internationally for that country.", "examples": ["", "E164", "PLUS_E164", "NATIONAL", "USA", "GBR"] }, "cache_days_global": { "type": "integer", "minimum": 0, "maximum": 30, "description": "Max age, in days, of a globally-shared cached result that may be returned." }, "cache_days_private": { "type": "integer", "minimum": 0, "maximum": 30, "description": "Max age, in days, of an account-private cached result that may be returned." }, "save_to_cache": { "type": "string", "enum": ["YES", "NO", "PRIVATE"], "description": "Whether new results should be written to the shared cache (`YES`), not cached (`NO`), or cached privately to this account (`PRIVATE`)." }, "get_ported_date": { "allOf": [{ "$ref": "#/components/schemas/YesNo" }], "default": "NO", "description": "Request the ported-date field when available." }, "get_landline_status": { "allOf": [{ "$ref": "#/components/schemas/YesNo" }], "default": "NO", "description": "Request the landline_status field when available." }, "get_imsi_hash": { "allOf": [{ "$ref": "#/components/schemas/YesNo" }], "description": "Request an IMSI hash under `current_network_details.imsi_hash` when available." }, "usa_status": { "allOf": [{ "$ref": "#/components/schemas/YesNo" }], "default": "NO", "description": "For US numbers, return live status instead of the default `NOT_AVAILABLE_NETWORK_ONLY`. Incurs an extra credit per lookup." } } }, "LookupRequest": { "title": "LookupRequest", "description": "Accepts either a flat single-number body or a nested batch body (up to 80 items).", "oneOf": [ { "$ref": "#/components/schemas/LookupRequestFlat" }, { "$ref": "#/components/schemas/LookupRequestNested" } ] }, "LookupRequestFlat": { "title": "LookupRequestFlat", "type": "object", "description": "Flat single-number request. Auto-converted server-side to a single-item nested request.", "required": ["api_key", "api_secret", "telephone_number"], "additionalProperties": false, "properties": { "api_key": { "type": "string" }, "api_secret": { "type": "string" }, "telephone_number": { "type": "string" }, "input_format": { "type": "string" }, "output_format": { "type": "string" }, "cache_days_global": { "type": "integer", "minimum": 0, "maximum": 30 }, "cache_days_private": { "type": "integer", "minimum": 0, "maximum": 30 }, "save_to_cache": { "type": "string", "enum": ["YES", "NO", "PRIVATE"] }, "get_ported_date": { "$ref": "#/components/schemas/YesNo" }, "get_landline_status": { "$ref": "#/components/schemas/YesNo" }, "get_imsi_hash": { "$ref": "#/components/schemas/YesNo" }, "usa_status": { "$ref": "#/components/schemas/YesNo" } } }, "LookupRequestNested": { "title": "LookupRequestNested", "type": "object", "required": ["api_key", "api_secret", "requests"], "additionalProperties": false, "properties": { "api_key": { "type": "string" }, "api_secret": { "type": "string" }, "requests": { "type": "array", "minItems": 1, "maxItems": 80, "items": { "$ref": "#/components/schemas/RequestItem" } } } }, "BalanceRequest": { "title": "BalanceRequest", "type": "object", "description": "Credentials-only body. Both `api_key` and `api_secret` are required.", "required": ["api_key", "api_secret"], "additionalProperties": false, "properties": { "api_key": { "type": "string" }, "api_secret": { "type": "string" } } }, "BalanceResponse": { "title": "BalanceResponse", "type": "object", "required": ["Status", "Credits"], "properties": { "Status": { "type": "string", "const": "OK" }, "Credits": { "type": "number", "description": "Remaining credit balance." } } }, "TelephoneNumberType": { "type": "string", "enum": [ "MOBILE", "LANDLINE", "VOIP", "PAGER", "PREMIUM", "TOLL_FREE", "SHARED_COST", "PERSONAL_NUMBER", "UNIVERSAL_ACCESS_NUMBER", "VOICEMAIL_ONLY", "STAGE_AND_SCREEN", "MACHINE_TO_MACHINE", "MSRN", "MOBILE_OR_LANDLINE", "UNKNOWN", "BAD_FORMAT" ] }, "LiveStatus": { "type": "string", "enum": [ "LIVE", "DEAD", "ABSENT_SUBSCRIBER", "NO_TELESERVICE_PROVISIONED", "NOT_AVAILABLE_NETWORK_ONLY", "NO_COVERAGE", "INCONCLUSIVE", "NOT_APPLICABLE" ] }, "NetworkAvailability": { "type": "string", "enum": ["AVAILABLE", "NOT_AVAILABLE", "NOT_APPLICABLE"] }, "IsPorted": { "type": "string", "enum": ["YES", "NO", "UNKNOWN"] }, "OriginalNetworkDetails": { "title": "OriginalNetworkDetails", "type": "object", "description": "Network that originally issued the range containing this number.", "properties": { "name": { "type": "string" }, "mccmnc": { "type": "string" }, "country_name": { "type": "string" }, "country_iso3": { "type": "string" }, "area": { "type": "string", "description": "Geographic area (may be empty for mobile ranges)." }, "country_prefix": { "type": "string" } } }, "CurrentNetworkDetails": { "title": "CurrentNetworkDetails", "type": "object", "description": "Network currently hosting the number (after any porting). Unlike `OriginalNetworkDetails`, `area` is omitted.", "properties": { "name": { "type": "string" }, "mccmnc": { "type": "string" }, "country_name": { "type": "string" }, "country_iso3": { "type": "string" }, "country_prefix": { "type": "string" }, "imsi_hash": { "type": "string", "description": "IMSI hash. Present only when `get_imsi_hash=YES` was requested and the current network is available." } } }, "EchoedRequestParameters": { "title": "EchoedRequestParameters", "type": "object", "description": "The request parameters applied to this result (after defaults and resolution).", "properties": { "telephone_number": { "type": "string" }, "input_format": { "type": "string" }, "output_format": { "type": "string" }, "save_to_cache": { "anyOf": [ { "type": "string", "enum": ["YES", "NO", "PRIVATE"] }, { "type": "null" } ] }, "cache_days_global": { "type": ["integer", "null"] }, "cache_days_private": { "type": ["integer", "null"] }, "get_ported_date": { "$ref": "#/components/schemas/YesNo" }, "get_landline_status": { "$ref": "#/components/schemas/YesNo" }, "get_imsi_hash": { "$ref": "#/components/schemas/YesNo" }, "usa_status": { "$ref": "#/components/schemas/YesNo" } } }, "ResultItemError": { "title": "ResultItemError", "type": "object", "required": ["error"], "properties": { "error": { "type": "string", "enum": ["INSUFFICIENT_CREDIT", "INTERNAL_ERROR", "TOO_MANY_REQUESTS", "NULL_RESULT"] } } }, "HlrResultItemSuccess": { "title": "HlrResultItemSuccess", "type": "object", "required": [ "error", "uuid", "request_parameters", "credits_spent", "detected_telephone_number", "formatted_telephone_number", "live_status", "original_network", "original_network_details", "current_network", "current_network_details", "is_ported", "sms_email", "mms_email", "timestamp" ], "properties": { "error": { "type": "string", "const": "NONE" }, "uuid": { "type": "string", "format": "uuid" }, "request_parameters": { "$ref": "#/components/schemas/EchoedRequestParameters" }, "credits_spent": { "type": "number" }, "detected_telephone_number": { "type": "string" }, "formatted_telephone_number": { "type": "string" }, "telephone_number_type": { "allOf": [{ "$ref": "#/components/schemas/TelephoneNumberType" }], "description": "Omitted on `/apiv2/mnp` responses for country code 1 (NANP) numbers." }, "live_status": { "$ref": "#/components/schemas/LiveStatus" }, "original_network": { "$ref": "#/components/schemas/NetworkAvailability" }, "original_network_details": { "$ref": "#/components/schemas/OriginalNetworkDetails" }, "current_network": { "$ref": "#/components/schemas/NetworkAvailability" }, "current_network_details": { "$ref": "#/components/schemas/CurrentNetworkDetails" }, "is_ported": { "$ref": "#/components/schemas/IsPorted" }, "sms_email": { "type": "string", "description": "SMS-to-email gateway address, empty string if unknown." }, "mms_email": { "type": "string", "description": "MMS-to-email gateway address, empty string if unknown." }, "ported_date": { "type": "string", "description": "ISO-8601 UTC timestamp, or a status string such as `NOT_AVAILABLE` / `NOT_APPLICABLE` if the supplier returned one. Only present when `get_ported_date=YES` was requested and the supplier returned a value." }, "landline_status": { "type": "string", "enum": [ "LIVE", "DEAD", "OUT_OF_ORDER", "NUMBER_CHANGED", "CALL_BARRED", "INCONCLUSIVE", "UNKNOWN_NOT_AUTH", "UNKNOWN_NOT_AVAIL", "UNKNOWN_NOT_IMPL", "UNKNOWN_REJECTED", "UNKNOWN_INTERWORKING", "ERROR_UNKNOWN_RESPONSE" ], "description": "Only present when `get_landline_status=YES` was requested and available." }, "raw_landline_response": { "type": "string", "description": "Raw response from the landline-status supplier. Only present when the supplier returned one." }, "disposable_number": { "type": "string", "enum": ["YES", "NO", "UNKNOWN"], "description": "Whether the number is a known disposable / temporary number. `UNKNOWN` if the supplier could not determine it." }, "timestamp": { "type": "string", "description": "ISO-8601 UTC timestamp of the underlying result (cached or live)." } } }, "ValidateResultItemSuccess": { "title": "ValidateResultItemSuccess", "type": "object", "description": "Format-only result. Omits live_status, current_network*, is_ported, caching fields, ported_date, landline_status and email gateways.", "required": [ "error", "uuid", "request_parameters", "credits_spent", "detected_telephone_number", "formatted_telephone_number", "telephone_number_type", "original_network", "original_network_details", "timestamp" ], "properties": { "error": { "type": "string", "const": "NONE" }, "uuid": { "type": "string", "format": "uuid" }, "request_parameters": { "type": "object", "properties": { "telephone_number": { "type": "string" }, "input_format": { "type": "string" }, "output_format": { "type": "string" } } }, "credits_spent": { "type": "number" }, "detected_telephone_number": { "type": "string" }, "formatted_telephone_number": { "type": "string" }, "telephone_number_type": { "$ref": "#/components/schemas/TelephoneNumberType" }, "original_network": { "$ref": "#/components/schemas/NetworkAvailability" }, "original_network_details": { "$ref": "#/components/schemas/OriginalNetworkDetails" }, "timestamp": { "type": "string" } } }, "HlrResponse": { "title": "HlrResponse", "type": "object", "required": ["results"], "properties": { "results": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/HlrResultItemSuccess" }, { "$ref": "#/components/schemas/ResultItemError" } ] } } } }, "ValidateResponse": { "title": "ValidateResponse", "type": "object", "required": ["results"], "properties": { "results": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/ValidateResultItemSuccess" }, { "$ref": "#/components/schemas/ResultItemError" } ] } } } }, "EndpointError": { "title": "EndpointError", "type": "object", "required": ["error", "message"], "properties": { "error": { "type": "string", "enum": ["UNAUTHORIZED", "BAD_REQUEST"] }, "message": { "type": "string" } } } }, "responses": { "Unauthorized": { "description": "Invalid or missing credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointError" }, "example": { "error": "UNAUTHORIZED", "message": "Invalid api_key or api_secret" } } } }, "BadRequest": { "description": "Request body failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointError" }, "example": { "error": "BAD_REQUEST", "message": "Invalid parameters" } } } }, "TooManyRequests": { "description": "The API is busy and the request was rejected at the handler level. Clients should back off and retry. Note: this is distinct from a per-result `TOO_MANY_REQUESTS` entry inside a successful `200` response, which indicates that one item in a batch was throttled while the rest succeeded.", "content": { "text/plain": { "schema": { "type": "string" }, "example": "Too many requests" } } } } } }