Phone Carrier Bulk Lookup API: Line Type & Operator

Look up the carrier, underlying carrier, line type, country code, region and city associated with each submitted mobile number. Simplify carrier-based grouping and virtual-number screening. The task uses the standard asynchronous batch workflow.

Input format

Upload a text file with one phone numbers per line. Normalize values before upload; for phone numbers, E.164 format is recommended.

+14155552671
+13105551234

Submit one country per task. Numbers are normalized against the task’s country (see country_code below), so numbers from another country in the same file are rewritten to that country and will not return correct results.

Create a task

POST https://api.numberchecker.ai/v1/tasks

curl --location 'https://api.numberchecker.ai/v1/tasks' \
--header 'X-API-Key: YOUR_API_KEY' \
--form 'file=@"./input.txt"' \
--form 'task_type="globalCarrier"' \
--form 'country_code="US"'

Request parameters

Field	Required	Description
file	yes	Text file, one phone number per line.
task_type	yes	globalCarrier. The per-country task types used before (usaCarrier, deCarrier, gbCarrier, …) are still accepted and resolve to this same product.
country_code	no	ISO-3166 alpha-2 country of the numbers in the file (US, DE, OM, …). Used to normalize numbers written without a country code. Inferred from the file when omitted.

The API returns a task ID. Keep this ID and use it to poll the task status.

Upload response

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "pending",
  "total": 5000,
  "estimated_amount": {
    "amount": "0.500000",
    "currency": "USD"
  },
  "message": "Task created successfully"
}

Check task status

POST https://api.numberchecker.ai/v1/gettasks

curl --location 'https://api.numberchecker.ai/v1/gettasks' \
--header 'X-API-Key: YOUR_API_KEY' \
--form 'task_id="d4g8o46p2jvh04o9uolg"'

Poll until status becomes exported. Do not treat pending or processing as a completed result.

Processing response

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "processing",
  "total": 5000,
  "success": 2500,
  "failure": 0
}

Exported response

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "exported",
  "total": 5000,
  "success": 5000,
  "failure": 0,
  "result_url": "https://example-link-to-results.zip",
  "actual_amount": {
    "amount": "2.000000",
    "currency": "USD"
  }
}

Result Fields

Field	Description	Example
number	Input phone number from the submitted file.	+14155552671
number_type	Line type returned for the number.	mobile
country_code	country_code value returned for the input.	sample value
carrier	Carrier value returned for the number.	Example Carrier
underlying_carrier	Carrier value returned for the number.	Example Carrier
region	region value returned for the input.	sample value
city	city value returned for the input.	sample value

Result file handling

Download the file from result_url only after the task is exported. Preserve the returned column names when processing the file downstream.

Response fields

Field	Description
created_at	Timestamp when the task was created.
updated_at	Timestamp of the latest task status update.
task_id	Unique task identifier.
status	pending, processing, exported, or failed.
total	Total input values processed.
success	Values processed successfully.
failure	Values that failed processing.
result_url	Download URL when the task is exported.
actual_amount	Final settled amount, when available.
estimated_amount	Estimated amount returned when the task is created.

Status codes

Status	Description
200	Request successful.
202	Task created successfully and estimated charge applied.
400	Invalid file, unsupported task type, or too few valid entries.
401	Missing or invalid API key.
402	Insufficient account balance.
403	Product not available for your account (discontinued or whitelist-only); contact support.
404	Task not found.
413	Uploaded file is too large.
500	Internal server error; retry later.
503	Product temporarily unavailable (paused for maintenance); nothing is charged, retry later.

Operational notes

• The task is asynchronous; use the task ID for status polling.
• Check product-specific input limits before uploading.
• Failed rows are reported in the exported result and reflected in the task counters.
• The fields above are based on the current live sample and may change when the upstream export schema changes.