Real-time carrier lookup API: one phone number, one request, one response

1. 1.Create an API key in Settings.
2. 2.Call GET /api/v1/balance to check the current balance.
3. 3.POST one phone number to /api/v1/check, or up to 100 phone numbers to /api/v1/batch-check.
4. 4.Read data.extra in the synchronous response.

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

X-API-Key: sk_your_api_key

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

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

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "carrier",
    "identifier": "+14155552671",
    "registered": true,
    "extra": {
      "carrier": "T-Mobile USA",
      "number_type": "mobile",
      "country_code": "US",
      "region": "California",
      "city": "San Francisco"
    }
  }
}

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "carrier",
    "identifier": "+14155550000",
    "registered": false,
    "extra": {
      "carrier": "",
      "number_type": "",
      "country_code": "",
      "region": "",
      "city": ""
    }
  }
}

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

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "carrier",
    "total": 2,
    "succeeded": 1,
    "failed": 1,
    "results": [
      {
        "identifier": "+14155552671",
        "exists": true,
        "registered": true,
        "extra": {
          "carrier": "T-Mobile USA",
          "number_type": "mobile",
          "country_code": "US",
          "region": "California",
          "city": "San Francisco"
        }
      },
      {
        "identifier": "+14155550000",
        "exists": false
      }
    ]
  }
}

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

• 5 requests in flight per userSingle and multi checks share this limit, and a multi request counts as one request no matter how many phone 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 multiExceeding 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 phone numbersResults preserve submission order and length. One multi check per account runs at a time; submit the next batch once the previous one has returned.

Upload a file of phone numbers and get a task id straight away. Then check the task by that id; once it succeeds you get a download link for the result archive.

• global_carrier_batchGlobal carrier lookup1,000–100,000 phone numbers per task$0.001 per phone number

curl -X POST "https://carrierlookup.online/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=global_carrier_batch \
  -F country=US \
  -F file=@numbers.txt

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "global_carrier_batch",
    "status": "processing",
    "country": "US",
    "total": 1000,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

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

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "global_carrier_batch",
    "status": "success",
    "country": "US",
    "total": 1000,
    "success_cnt": 990,
    "failure_cnt": 10,
    "result_url": "https://…/result.zip",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

• One phone number per line.Upload a .txt or .csv with one phone number in E.164 form per line. Send `country` with the file: it completes numbers that have no country code, and the file is validated against it.
• No per-phone number progress.status is processing, success or failed. Large lists take a while; do not poll more often than once every 30 seconds.
• Billing.The full file is reserved on submit. When the task finishes you are charged only for the phone numbers that were actually checked and the rest is refunded. A failed task is refunded in full.
• Result files expire.The download link is generated on demand and points at a time-limited file. Download the result soon after the task finishes.