Integrating the Carrier Lookup API: Original Carrier and Line Type Workflows

Integrate the Carrier Lookup API to inspect original carrier allocation, line type, and numbering geography using realtime REST endpoints and bulk file processing.

The Carrier Lookup API provides original carrier and number-allocation context for telecommunication data management. When organizations query a phone number using the API, the service returns data indicating the operator to which the number block was initially assigned, along with line type and allocation geography. This information represents the administrative assignment defined by numbering plans, providing stable telecommunication context for internal routing and risk assessment workflows. Because it reflects initial allocation rather than active subscriber network routing, teams integrate CarrierLookup to inspect foundational number parameters across realtime single endpoints, multi-item synchronous queries, or asynchronous bulk batch files.

Core Allocation Data and Line Type Attributes

Telecommunication numbering arrangements follow international standards such as ITU-T Recommendation E.164, which defines global numbering plans with country codes and subscriber numbers. Within these structures, regulatory authorities assign specific number blocks to network operators. CarrierLookup exposes these foundational properties through its original carrier lookup capability.

The response schema organizes telecommunication context into distinct data points:

• carrier: The communication provider to which the numbering range was originally allocated.
• underlying_carrier: The underlying infrastructure provider associated with the assigned range.
• number_type: The classification of the line, such as mobile or wireline assignment.
• country_code: The international dialing prefix matching the allocation territory.
• region and city: The administrative geographic territory designated in the numbering assignment plan.

These data points establish static range attributes. Because numbers retain their initial range definitions regardless of subscriber activity, this data acts as a consistent reference for filtering, telecommunication analysis, and internal record organization.

Realtime Single and Multi-Check Integration

Integrating realtime lookups allows backend systems to evaluate phone numbers synchronously during application intake or review workflows. Requests authenticate using the X-API-Key HTTP header submitted from a secure application server.

Single-Number Check Workflow

To check an individual identifier, submit a request to POST /api/v1/check. The payload requires a phone number formatted in international standard E.164 syntax, featuring a leading plus sign, country code, and subscriber digits without spaces or punctuation.

Upon processing, the server returns a JSON response containing code, msg, and a flat data object. The data payload contains service_type, identifier, carrier, underlying_carrier, number_type, country_code, region, and city. Optional allocation fields may return empty if specific details are unlisted for that range, yet the lookup registers as completed.

Synchronous Multi-Check Workflow

For batches requiring immediate evaluation, organizations call POST /api/v1/batch-check. This endpoint processes multiple E.164 numbers synchronously within a single call. The response returns high-level execution metrics alongside an ordered array:

• service_type: Confirms the executed lookup service.
• total: The count of identifiers submitted.
• succeeded: The number of items successfully evaluated.
• failed: The number of items that encountered processing failures.
• results: An ordered collection of items, each containing identifier and exists.

In this synchronous multi response, an exists=false value indicates that no standard allocation record was returned, rather than asserting a disconnected or malformed line.

Asynchronous Bulk File Processing Workflow

When processing expansive inventories of telecommunication records, teams utilize the asynchronous carrier_batch service. This workflow handles file-based submissions without keeping client connections open.

Task Submission and Structure

Submit batch requests via POST /api/v1/bulk-tasks using multipart form data. The upload requires a plain TXT or CSV file containing one identifier per line, along with a specified ISO country parameter. Applicable per-product limits apply to task sizes, and readers can review current operational parameters in the official API documentation.

During ingestion, automated preprocessing reviews list contents to filter duplicates, malformed entries, and rows matching countries outside the selected target. Processing excludes these non-conforming entries from lookup accounting.

Task Lifecycle and Retrieval

Clients monitor batch progress by querying GET /api/v1/bulk-tasks/{id}. Polling schedules should follow a measured cadence, checking no more frequently than once every 30 seconds. The task lifecycle transitions through three formal states:

• processing: The file is undergoing system evaluation.
• failed: The task encountered an execution error or failed intake requirements.
• success: Range evaluation is complete and output is available.

When a task finishes with success, the endpoint supplies a single CSV file. The output structure contains seven standardized headers: identifier, carrier, underlying_carrier, number_type, country_code, region, and city. The identifier in this file is rendered as digits with the country code, omitting plus symbols.

Operational Limits and Coverage Specifications

Implementing a carrier lookup integration requires aligning technical architecture with system concurrency and geographic parameters.

Geographic coverage features distinct regional rules. Realtime single-number lookups accommodate inquiries across mainland China (+86), Hong Kong (+852), and Macau (+853) for modest operational volumes. However, bulk batch files do not accept numbers from these three regions. Coverage status for Taiwan (+886) remains unconfirmed.

To verify account status before invoking checks, query GET /api/v1/balance to retrieve the current balance without consuming lookups. Furthermore, newly registered users can contact support to receive 100 free checks to validate their integration workflows against production endpoints.

FAQ

How does the API handle numbers that have been ported between networks?

CarrierLookup reports the operator to which the numbering range was originally assigned by administrative authorities. In telecommunications, consumers can switch providers while retaining their number, as described in Porting: Keeping Your Phone Number When You Change Providers. Consequently, the carrier field reflects this historical range allocation rather than the current serving operator, maintaining an unchanging structural attribute for numbering analysis.

What distinguishes the realtime multi-check from the bulk batch service?

The realtime multi-check endpoint POST /api/v1/batch-check evaluates numbers synchronously, returning an immediate JSON payload with service_type, total, succeeded, failed, and ordered results showing identifier and an exists boolean. In contrast, the bulk batch service processes lists asynchronously from submitted CSV or TXT files. Once background analysis finishes, bulk tasks provide a downloadable CSV containing full allocation columns including carrier, underlying_carrier, number_type, country_code, region, and city.

Do the region and city fields indicate the physical location of the device?

The region and city fields designate the geographical boundary of the initial numbering plan allocation, corresponding to the administrative assignment of the phone exchange. These values provide territorial context for the subscriber number block. They represent static numbering assignments rather than realtime mobile device positioning, live cellular tower connections, or the physical whereabouts of an individual subscriber.

Learn More

Choose the product information that fits the next step in your workflow.

• View the product documentation →
• Talk to the team →