Reference

CarrierLookup API reference

Every endpoint shares one API key and one balance.

Item	Value
Base URL	https://api.carrierlookup.online
Auth header	X-API-Key: sk_your_api_key
Response envelope	{ code, msg, data }

Prices are not listed here; every product is billed per successful check. See pricing

Authentication

Use an API key created in Settings and send it with every request.

Auth header

X-API-Key: sk_your_api_key

Keep your API key secretAlways call this endpoint from your server. Anyone holding the key can spend your balance.

Synchronous checks

POST/api/v1/checkPOST/api/v1/batch-check

Submit one phone number, or up to 100 in one request, and read the result in the same response. No polling, no callbacks. An undetermined result returns 422 with code 42200 and is not charged. A multi request keeps the input order, bills each identifier independently, and has 300 seconds to finish — if it does not, the whole request fails and every charge is refunded.

Parameters

Field	Type	Description
`service_type`	string	Product code, one of the products listed below.
`identifier`	string	Single check: one phone number. The server normalizes it.
`identifiers`	string[]	Multi check: 1 to 100 phone numbers. The response preserves this order.

Products in this group

Original Carrier LookupcarrierFind the carrier a number was originally allocated to, with line type and location.Product page

Original Carrier Lookup

carrierphone

Find the carrier a number was originally allocated to, with line type and location.

Single check

POST/api/v1/check

Request

curl -X POST "https://api.carrierlookup.online/api/v1/check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "carrier", "identifier": "+12345678900" }'

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "carrier",
    "identifier": "+12345678900",
    "carrier": "T-Mobile",
    "underlying_carrier": "",
    "number_type": "Fixed Line or Mobile",
    "country_code": "US",
    "region": "OH",
    "city": "AKRON"
  }
}

Response fields

Field	Type	Description
`carrier`	string	Carrier the number was originally allocated to. Not the current carrier after porting.
`underlying_carrier`	string	Underlying carrier reported by the provider when it differs from the allocated one; empty string when the provider does not supply one.
`number_type`	string	Line type reported by the provider; empty when unavailable.
`country_code`	string	ISO country code the number belongs to.
`region`	string	Allocation region; empty when the provider does not supply one.
`city`	string	Allocation city; empty when the provider does not supply one.

Multi check

POST/api/v1/batch-check

Request

curl -X POST "https://api.carrierlookup.online/api/v1/batch-check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "carrier", "identifiers": ["+12345678900", "12345"] }'

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "carrier",
    "total": 2,
    "succeeded": 1,
    "failed": 1,
    "results": [
      {
        "identifier": "+12345678900",
        "exists": true,
        "carrier": "T-Mobile",
        "underlying_carrier": "",
        "number_type": "Fixed Line or Mobile",
        "country_code": "US",
        "region": "OH",
        "city": "AKRON"
      },
      {
        "identifier": "12345",
        "exists": false
      }
    ]
  }
}

Response fields

Field	Type	Description
`exists`	boolean	Whether this number produced a result. false means the format was invalid, the result was undetermined, or the check failed; when false, none of the fields below are present.
`carrier`	string	Carrier the number was originally allocated to. Not the current carrier after porting.
`underlying_carrier`	string	Underlying carrier reported by the provider when it differs from the allocated one; empty string when the provider does not supply one.
`number_type`	string	Line type reported by the provider; empty when unavailable.
`country_code`	string	ISO country code the number belongs to.
`region`	string	Allocation region; empty when the provider does not supply one.
`city`	string	Allocation city; empty when the provider does not supply one.

Asynchronous checks

POST/api/v1/bulk-tasksGET/api/v1/bulk-tasks/{id}

Upload a file and get a task id straight away, then check that id until it succeeds. The successful response carries result_url, the result download link. Only two actions exist: submit and check. Poll no more often than once every 30 seconds.

Parameters

Field	Type	Description
`service_type`	string	Bulk product code, one of the products listed below.
`country`	string	ISO 3166-1 code such as `US`. Required for number tasks: every number must include its country code and belong to this country (numbers that do not are left out and not charged); it also selects routing. In multipart it must come before `file`.
`file`	file	A `.txt` or `.csv` with one identifier per line, up to `max_file_bytes` (20MB by default).
`Idempotency-Key`	header	Optional, up to 128 characters. Replaying the same key returns the original task instead of creating a second one.

Products in this group

Global carrier lookupcarrier_batchUpload a whole file of numbers: carrier, underlying carrier, line type, country, region and city for each one — the same fields as the realtime carrier lookup.Product page

Global carrier lookup

carrier_batchphone1,000–500,000 per task

Upload a whole file of numbers: carrier, underlying carrier, line type, country, region and city for each one — the same fields as the realtime carrier lookup.

Submit a task

POST/api/v1/bulk-tasks

Request

curl -X POST "https://api.carrierlookup.online/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=carrier_batch \
  -F country=US \
  -F [email protected]

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "carrier_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1015,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Check the task

GET/api/v1/bulk-tasks/{id}

Request

curl "https://api.carrierlookup.online/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "carrier_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1000,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 12,
    "preparing": false,
    "success_cnt": 990,
    "failure_cnt": 10,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Result columns

Field	example:	Description
`identifier`	12345678900	The submitted number as plain digits with the country code, no plus sign or spaces (e.g. 12345678900).
`carrier`	T-Mobile	Carrier the number was originally allocated to. Not the current carrier after porting.
`underlying_carrier`		Underlying carrier reported by the provider when it differs from the allocated one; empty when the provider does not supply one.
`number_type`	Fixed Line or Mobile	Line type reported by the provider, such as Fixed Line or Mobile; empty when unavailable.
`country_code`	US	ISO country code the number belongs to.
`region`	CA	Allocation region; empty when the provider does not supply one.
`city`	LOS ANGELES	Allocation city; empty when the provider does not supply one.

Balance

GET/api/v1/balance

Read the current account balance in USD micros. Read-only: it creates no check record and charges nothing.

Balance

GET/api/v1/balance

Request

curl "https://api.carrierlookup.online/api/v1/balance" \
  -H "X-API-Key: sk_your_api_key"

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "balance_micros": 12500000
  }
}

Concurrency, timeouts, and retry behavior

Carrier lookups are synchronous. Use the returned code to decide whether to accept the result or retry later.

Field	Description
`5 requests in flight per user`	Single and multi checks share this limit, and a multi request counts as one request no matter how many numbers it carries. On top of that, only one multi check per account runs at a time; a second one is rejected until the first finishes. Hitting either limit returns code 42901 immediately with no charge, plus a Retry-After header — resubmit once an in-flight request finishes.
`60s single, 300s multi`	Exceeding the time limit returns code 50400 with no charge. A multi check that times out fails as a whole — no partial results, and the full amount is refunded.
`A multi check takes up to 100 numbers`	Results preserve submission order and length. One multi check per account runs at a time; submit the next batch once the previous one has returned.

Error codes

Code	Description
`40000`	Unsupported service type or conflicting request fields
`40001`	Invalid JSON body
`40002`	Invalid number
`40100`	Missing or invalid API key
`40200`	Insufficient balance
`42200`	The number could not be determined at this time. No data is returned and the request is not charged
`42900`	A usage quota is exhausted, or there are too many unfinished orders
`42901`	All five in-flight request slots are occupied, or a multi check is already running on this account; submit after an in-flight request finishes. The rejected request is not charged and carries a Retry-After header
`50303`	The service is at capacity right now; not charged. Wait for the Retry-After seconds and resubmit the same request
`50400`	The check did not finish within its timeout and is not charged; retry it. A batch timeout fails the whole batch and refunds the full amount
`50300`	Lookup service maintenance