--- type: "firecrawl-provider" description: "Check whether a phone number is live, and find the network that serves it." use_when: "Check whether a phone number is live, and find the network that serves it." categories: "People" capabilities: 2 pricing: "2 credits per billed unit; see each capability for its unit and maximum." --- # HLR Lookup on Firecrawl Alexandria Check whether a phone number is live, and find the network that serves it. - Categories: People - Category index: [People category](https://alexandria.firecrawl.dev/agents/categories/people) - Provider key: `hlrlookup` - Access: Firecrawl credits - Cost (Phone live status): 2 credits per HLR Lookup credit - Cost (Phone network): 2 credits per MNP lookup ## More - [Human guide](https://www.firecrawl.dev/app/alexandria/hlrlookup) - [OpenAPI spec](https://alexandria.firecrawl.dev/agents/providers/hlrlookup/openapi.json) ## Capabilities - [Phone live status](https://alexandria.firecrawl.dev/agents/providers/hlrlookup/people/phone-verify): One result in results[0]. live_status says whether the line is reachable. Some networks give NOT_AVAILABLE_NETWORK_ONLY and the lookup is still charged. sms_email and mms_email are carrier gateway addresses when known. - [Phone network](https://alexandria.firecrawl.dev/agents/providers/hlrlookup/people/phone-network): One result in results[0]: current_network_details and is_ported. live_status is NOT_AVAILABLE_NETWORK_ONLY because this route does not check the line. telephone_number_type is omitted for +1 numbers. ## 1. Choose this provider when Check whether a phone number is live, and find the network that serves it. ## 2. Minimal request Call `POST https://api.firecrawl.dev/v2/scrape` with `{ alexandria: { provider, capability, options } }`. For a batch, send `{ alexandria: [...] }` with up to 10 calls. ```json { "provider": "hlrlookup", "capability": "people/phone-verify", "options": { "telephone_number": "" } } ``` ## 3. Add provider options Use only the options needed for the task: - `telephone_number` (string, required): International number in E.164 digits without the leading +, such as 447540822872. A national number needs input_format. Example: `` - `input_format` (string): ISO3 country code when telephone_number is national, such as USA or GBR. Without it a national number can be read as another country's and is still charged. Example: `` - `output_format` (string): Format of formatted_telephone_number: E164, PLUS_E164, NATIONAL, or an ISO3 country code. Example: `` - `usa_status` (string): YES only for +1 numbers, to get a live status for a US mobile. That lookup spends two HLR credits. Example: `YES` ## 4. Request through your preferred interface ### JavaScript ```javascript const result = await firecrawl.scrape({ alexandria: { provider: "hlrlookup", capability: "people/phone-verify", options: { telephone_number: "", }, }, }); ``` ### Python ```python result = firecrawl.scrape_alexandria({ "provider": "hlrlookup", "capability": "people/phone-verify", "options": { "telephone_number": "" } }) ``` ### cURL ```sh curl https://api.firecrawl.dev/v2/scrape \ -H "Authorization: Bearer $FIRECRAWL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "alexandria": { "provider": "hlrlookup", "capability": "people/phone-verify", "options": { "telephone_number": "" } } }' ``` ### CLI ```sh firecrawl scrape 'hlrlookup/people/phone-verify' \ --options '{"telephone_number":""}' ``` ### MCP Call the FCX MCP retrieve tool with this object: ```json { "provider": "hlrlookup", "capability": "people/phone-verify", "options": { "telephone_number": "" } } ``` Ask for only the returned fields needed by the task. ## 5. Full request shape ```json { "provider": "hlrlookup", "capability": "people/phone-verify", "options": { "telephone_number": "" } } ``` ## 6. Response data The response includes `success`, `provider`, `capability`, `creditsCost` and `data`. This example shows the provider payload in `data`: ```json { "results": [ { "error": "", "uuid": "", "credits_spent": 0, "detected_telephone_number": "", "formatted_telephone_number": "", "telephone_number_type": "", "live_status": "", "original_network_details": {}, "current_network_details": {}, "is_ported": "", "timestamp": "", "sms_email": "", "mms_email": "" } ] } ``` ## API reference-derived contract The following capability contract is generated from the same normalized Alexandria API reference exposed in the API spec. ### Phone live status - Capability: `people/phone-verify` - Description: One result in results[0]. live_status says whether the line is reachable. Some networks give NOT_AVAILABLE_NETWORK_ONLY and the lookup is still charged. sms_email and mms_email are carrier gateway addresses when known. - Instructions: Check whether a mobile number is live on its network, which network serves it now, and whether it was ported. 15 Firecrawl credits per lookup, 30 for a US mobile with usa_status YES. Landlines (NO_COVERAGE) and bad formats cost nothing. Use people/phone-network when the live status is not needed. - Cost: 2 credits per HLR Lookup credit - Capability file: [Phone live status](https://alexandria.firecrawl.dev/agents/providers/hlrlookup/people/phone-verify) Accepted options: - `telephone_number` (string, required): International number in E.164 digits without the leading +, such as 447540822872. A national number needs input_format. Example: `` - `input_format` (string): ISO3 country code when telephone_number is national, such as USA or GBR. Without it a national number can be read as another country's and is still charged. Example: `` - `output_format` (string): Format of formatted_telephone_number: E164, PLUS_E164, NATIONAL, or an ISO3 country code. Example: `` - `usa_status` (string): YES only for +1 numbers, to get a live status for a US mobile. That lookup spends two HLR credits. Example: `YES` Response schema example: ```json { "results": [ { "error": "", "uuid": "", "credits_spent": 0, "detected_telephone_number": "", "formatted_telephone_number": "", "telephone_number_type": "", "live_status": "", "original_network_details": {}, "current_network_details": {}, "is_ported": "", "timestamp": "", "sms_email": "", "mms_email": "" } ] } ``` ### Phone network - Capability: `people/phone-network` - Description: One result in results[0]: current_network_details and is_ported. live_status is NOT_AVAILABLE_NETWORK_ONLY because this route does not check the line. telephone_number_type is omitted for +1 numbers. - Instructions: Find the network that currently serves a phone number and whether it was ported, without checking whether the line is live. 5 Firecrawl credits per lookup; NO_COVERAGE and bad formats cost nothing. Use people/phone-verify for live status. - Cost: 2 credits per MNP lookup - Capability file: [Phone network](https://alexandria.firecrawl.dev/agents/providers/hlrlookup/people/phone-network) Accepted options: - `telephone_number` (string, required): International number in E.164 digits without the leading +, such as 447540822872. A national number needs input_format. Example: `` - `input_format` (string): ISO3 country code when telephone_number is national, such as USA or GBR. Without it a national number can be read as another country's and is still charged. Example: `` - `output_format` (string): Format of formatted_telephone_number: E164, PLUS_E164, NATIONAL, or an ISO3 country code. Example: `` Response schema example: ```json { "results": [ { "error": "", "uuid": "", "credits_spent": 0, "detected_telephone_number": "", "formatted_telephone_number": "", "telephone_number_type": "", "live_status": "", "original_network_details": {}, "current_network_details": {}, "is_ported": "", "timestamp": "" } ] } ```