---
canonical_url: "https://docs.composio.dev/toolkits/hlr_lookup"
markdown_url: "https://docs.composio.dev/toolkits/hlr_lookup.md"
product: "platform"
version: null
last_updated: null
---

# HLR Lookup

HLR Lookup provides phone-number validation, network and portability intelligence, account balance checks, and asynchronous bulk HLR processing.

- **Category:** phone & sms
- **Auth:** API_KEY
- **Composio-managed OAuth available?** N/A
- **Tools:** 14
- **Triggers:** 0
- **Slug:** `HLR_LOOKUP`
- **Version:** 00000000_00

## Tools

### Check Phone Status

**Slug:** `HLR_LOOKUP_CHECK_PHONE_STATUS`

Run full HLR lookups for 1-80 phone numbers. This processes sensitive phone data and spends credits; optional status features can increase the cost.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `requests` | array | Yes | One to 80 phone-number lookup requests. Each item defaults to private caching and disables optional billable features. |
| `account_id` | string | No | Optional caller account reference sent only in the provider's AccountID header. This is not an authentication credential. |
| `reference_id` | string | No | Optional caller reference sent only in the provider's ReferenceID header for request reconciliation. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Batch

**Slug:** `HLR_LOOKUP_CREATE_BATCH`

Create an empty persistent HLR_V2 batch. Creation has no documented charge and handles no phone data; later uploads persist sensitive phone data, and processing can spend credits.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `filename` | string | Yes | Descriptive source filename for the new batch. |
| `batch_arguments` | object | No | Processing options for the future HLR batch. Private caching and non-billable feature defaults are applied when omitted. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Batch

**Slug:** `HLR_LOOKUP_DELETE_BATCH`

Permanently delete one HLR batch and its results. This action is irreversible: never invoke it without explicit authorization, and download all needed results before deletion. It does not select a batch automatically.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `batch_id` | string | Yes | ID of the batch to permanently delete. Confirm explicit authorization, the intended account, and that all needed results were downloaded first. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Download Batch Results

**Slug:** `HLR_LOOKUP_DOWNLOAD_BATCH_RESULTS`

Download a completed batch's full, unpaginated CSV or JSON result export, including source phone values and sensitive HLR intelligence, as a file reference. Select the required format explicitly.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `format` | string ("CSV" | "JSON") | Yes | Required result export format. CSV and JSON use different provider routes. |
| `batch_id` | string | Yes | ID of a batch whose status is COMPLETE. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Credit Balance

**Slug:** `HLR_LOOKUP_GET_BALANCE`

Return the connected HLR Lookup account's remaining credit balance. This zero-credit read is the approved authentication check and does not process a phone number.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Batch

**Slug:** `HLR_LOOKUP_GET_BATCH`

Return metadata and current progress for one HLR batch. Use it to follow an asynchronous batch until status is COMPLETE.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `batch_id` | string | Yes | ID of a batch owned by the connected account. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Batches

**Slug:** `HLR_LOOKUP_LIST_BATCHES`

List the connected account's HLR batches with their metadata and progress. The response reports provider offset and limit values, but the API documents no pagination inputs.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Run MNP Lookup

**Slug:** `HLR_LOOKUP_MNP_LOOKUP`

Look up network and mobile-number-portability data for 1-80 phone numbers. This processes sensitive phone data and spends credits; requesting the optional ported date is the only MNP feature that can add a surcharge.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `requests` | array | Yes | One to 80 portability lookup requests. Each item defaults to private caching and disables the optional billable ported-date feature. |
| `account_id` | string | No | Optional caller account reference sent only in the provider's AccountID header. This is not an authentication credential. |
| `reference_id` | string | No | Optional caller reference sent only in the provider's ReferenceID header for request reconciliation. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Pause Batch

**Slug:** `HLR_LOOKUP_PAUSE_BATCH`

Pause processing one HLR batch. This action returns when the command is accepted and does not poll for a status change.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `batch_id` | string | Yes | ID of the uploaded HLR batch to update. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Schedule Batch

**Slug:** `HLR_LOOKUP_SCHEDULE_BATCH`

Schedule processing of one uploaded HLR batch at a UTC time. Scheduled processing of sensitive phone data can irreversibly spend credits, so never invoke this action automatically. This action does not poll for processing or completion.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `batch_id` | string | Yes | ID of the uploaded HLR batch to update. |
| `scheduled_start` | string | Yes | ISO 8601 UTC time at which batch processing should start. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Start or Resume Batch

**Slug:** `HLR_LOOKUP_START_OR_RESUME_BATCH`

Start or resume processing one uploaded HLR batch. Processing sensitive phone data can irreversibly spend credits, so never invoke this action automatically. This action returns when the command is accepted and does not poll for completion.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `batch_id` | string | Yes | ID of the uploaded HLR batch to update. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Upload Batch CSV

**Slug:** `HLR_LOOKUP_UPLOAD_BATCH_CSV`

Upload a CSV file of sensitive phone data into an empty HLR batch. The provider permits one source upload; repeating it on a populated batch is documented to fail.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `column` | integer | No | Zero-based CSV column containing phone numbers. Defaults to the first column; the provider does not document a maximum. |
| `batch_id` | string | Yes | ID of an empty HLR_V2 batch owned by the connected account. |
| `csv_file` | object | Yes | CSV file whose raw bytes contain the phone-number source data. No official row or file-size limit is documented. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Upload Batch Phone Numbers

**Slug:** `HLR_LOOKUP_UPLOAD_BATCH_JSON`

Upload 1-100,000 sensitive phone numbers into an empty HLR batch as a compact JSON array. The UTF-8 body must not exceed 2 MiB, and a populated batch cannot be uploaded again.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `batch_id` | string | Yes | ID of an empty HLR_V2 batch owned by the connected account. |
| `phone_numbers` | array | Yes | Phone numbers to upload. The provider accepts 1-100,000 values, and their compact UTF-8 JSON array must not exceed 2 MiB. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Validate Phone Numbers

**Slug:** `HLR_LOOKUP_VALIDATE_NUMBER`

Validate formatting and original-network information for 1-80 phone numbers without a live HLR lookup. It costs zero credits but still processes sensitive phone data.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `requests` | array | Yes | One to 80 numbers to validate, with optional input and output formatting. |
| `account_id` | string | No | Optional caller account reference sent only in the provider's AccountID header. This is not an authentication credential. |
| `reference_id` | string | No | Optional caller reference sent only in the provider's ReferenceID header for request reconciliation. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |