# CarrierLookup

> CarrierLookup is a real-time phone carrier lookup platform. Its core capability is a synchronous single-number lookup: submit one phone number in E.164 form to the REST API and the carrier data comes back in the same HTTP response — no task queue, no polling, no callbacks. Multi-number synchronous requests are also available. An asynchronous bulk option exists for whole large lists, but the product is the realtime lookup.

## Products (realtime lookups)

Results arrive in the same HTTP response, for one number or for several numbers sent in a single request.

- Original Carrier Lookup (`carrier`): returns the network a phone number was **originally allocated to**, with line type, country, and the allocation region and city when the provider supplies them.

## API

- Realtime: `POST /api/v1/check` (one number) and `POST /api/v1/batch-check` (up to 100 numbers in one request). Both return results synchronously in the same HTTP response.
- Secondary, for whole large lists only: `POST /api/v1/bulk-tasks` (upload a file, returns a task id) and `GET /api/v1/bulk-tasks/{id}` (status and result download link). A bulk task takes a `country`: it completes numbers submitted without a country code, and the file is validated against it.
- Authentication: API key from the dashboard. The same key and the same balance cover every product.
- Realtime request fields: `service_type` is `carrier`; `identifier` is one phone number in E.164 form (a plus sign, the country code, then the subscriber number, with no spaces or separators).
- Main response field: `extra`, an object whose keys are declared by the product — `carrier`, `number_type`, `country_code`, `region`, `city`. The key set does not change when the provider returns nothing for a field: the same keys come back with `""`.
- The API path is `/api/v1`. Current per-request and per-task limits are documented in the API docs.

## Pricing

CarrierLookup charges per number: $0.01 for a completed carrier lookup. Balance is drawn down as lookups run. Permanent balance does not expire or renew. A 30-day plan renews automatically every 30 days until auto-renewal is turned off; turning it off stops future charges without removing the current plan or balance. A rate-limited public demo lookup is available without signing in.

## Also available: asynchronous bulk lookup (secondary)

For whole large lists that far exceed a realtime request, CarrierLookup also offers an asynchronous bulk lookup: upload a file from 1,000 numbers, receive a task id, download a result file when it finishes. It is an add-on to the realtime product, not a separate product line. Bulk product: `carrier_batch` — one country is selected per task and submitted with the file. The estimate is held when the task is submitted and the unanswered part is returned to the balance on settlement.

## Important Notes

- The result describes the network a number was **originally allocated to** — the carrier that was assigned that number range. It does not follow number portability, so it is not necessarily the carrier serving the number today.
- It is not a reachability check. A returned carrier does not mean the number is in service, switched on, or able to receive anything.
- No message, call, or SMS is ever sent to the number being looked up. Lookups run against allocation data, so the person behind the number receives nothing.
- `number_type`, `region` and `city` are empty when the provider does not supply them. Empty is a "not available" answer, not an error.
- Lookups that fail or come back undetermined are refunded and must not be read as "this number has no carrier".
- A carrier result is not identity verification, not proof of ownership, and not consent to be contacted.

## Methodology and Guides

- [How carrier lookup works](https://carrierlookup.online/how-it-works): request lifecycle, limits, and interpretation boundaries.
- [API documentation](https://carrierlookup.online/api-docs): authentication, endpoints, response shape, and error codes.
- [MCP server](https://carrierlookup.online/mcp-docs): run lookups from Claude, Cursor, or any MCP client with an existing API key.
- [Pricing](https://carrierlookup.online/pricing): permanent top-ups and 30-day plans.