--- title: "HLR lookup for a mobile number" method: POST path: "/hlr-lookup" tags: ["Phone"] --- # HLR lookup for a mobile number `POST /hlr-lookup` ## Request - Base URL: `https://app.1lookup.io/api/v1` - URL: `https://app.1lookup.io/api/v1/hlr-lookup` - Auth: HTTP bearer Queries the mobile network for live subscriber status, roaming state and current carrier. Costs 5 credits; a number the network reports as invalid costs nothing. ## Request body - object - `phone_number` string, required: Mobile number in E.164 format. - `bypass_cache` boolean: Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual. ## Response `200` Lookup completed. `metadata.credits_used` says what it cost. - object - `success` true, required - `data` HlrResult, required: Live network status of a mobile number. - `request` LookupRequest, required - `id` string, uuid, required: Id of this lookup. - `type` string, required: Lookup type, such as `phone`, `email` or `hlr_lookup`. - `input` string, required: The input as it was looked up, after normalization. - `timestamp` string, date-time, required: When the lookup ran. - `processing_time_ms` integer, required: Server-side processing time, in milliseconds. - `risk_assessment` RiskAssessment - `fraud_score` number: 0 to 100, higher is riskier. Not returned by every product (phone validation has none). - `risk_level` 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL', required - `risk_factors` string[], required: Codes for what raised the risk, such as `NOT_REACHABLE`, `DISPOSABLE_EMAIL` or `NO_MATCH_FOUND`. - `confidence_level` number, required: 0 to 100. - `classification` object, required - `lookup_type` 'HLR', required - `connectivity_status` string, required: Status as the network reported it, such as CONNECTED, ABSENT, ABSENT_SUBSCRIBER, INVALID_MSISDN or UNDETERMINED. `is_valid` and the risk fields come from a normalized reading of it. - `is_valid` boolean, required: False when the network reports the number invalid or unallocated. Such a lookup is not charged. - `is_ported` boolean, required - `is_roaming` boolean, required - `mccmnc` string - `mcc` string - `mnc` string - `insights` object, required - `hlr_result` object, required - `id` string - `msisdn` string: The number, in international format without +. - `connectivity_status` string - `current_carrier` string: Carrier the number is on now: the ported carrier when ported, otherwise the original. - `current_mccmnc` string - `original_carrier` string - `country` string - `country_code` string - `country_prefix` string - `is_ported` boolean - `ported_carrier` string, nullable - `ported_country` string, nullable - `is_roaming` boolean - `roaming_carrier` string, nullable - `roaming_country` string, nullable - `imsi` string, nullable - `data_source` string: Where the answer came from. LIVE_HLR is a live network query; MNP_DB is the portability database (most US and Canada numbers), which shows the number is assigned, not that the handset is on. - `timestamp` string - `recommendations` Recommendations, required - `primary_action` 'APPROVE' | 'VERIFY' | 'REVIEW' | 'BLOCK', required - `secondary_actions` string[], required - `user_message` string, required: One plain sentence describing the result. - `business_rules` object, required: Product-specific yes/no rules, such as `sms_allowed` and `voice_allowed` for a phone number. - `metadata` LookupMetadata, required - `api_version` string, required - `schema_version` string, required - `credits_used` integer: Credits this call cost. 0 for a no-match on success-billed products, and for a cached result you ran yourself. - `credits_remaining` integer: Credits left on the account after this call. - `cache_hit` boolean, required: True when the result came from the 7-day cache. - `cached_at` string, date-time: When the cached result was first looked up. Only on cache hits. - `data_sources` string[], required: Generic labels for the kinds of data consulted. - `fallback_used` boolean: Email verification only: a second verification ran. - `lookup_source` 'standard' | 'premium': Reverse phone lookup only: which record was read. ## Other responses - `400`: `INVALID_REQUEST`: The body is not valid JSON; `MISSING_FIELD`: The request field is missing; `INVALID_INPUT`: The input is not a string, or does not match the expected format; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged - `401`: `UNAUTHORIZED`: Invalid or missing API key - `402`: `INSUFFICIENT_CREDITS`: Not enough credits for the request - `403`: `UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key - `429`: `RATE_LIMIT_EXCEEDED`: Too many requests - `500`: `INTERNAL_ERROR`: Internal server error - `503`: `SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds --- [API](https://skmtc.dev/1lookup/apis/1lookup-api.md) · [All operations](https://skmtc.dev/1lookup/apis/1lookup-api/llms.txt) · [OpenAPI document](https://skmtc.dev/1lookup/apis/1lookup-api/revisions/57b6d8ba04ac?raw)