Phone Carrier Bulk Lookup API: Line Type & Operator

Look up carrier and line-type information for phone numbers in bulk. Set task_type to the country-specific carrier code (for example usaCarrier, deCarrier, idCarrier); use us_carrier_premium for advanced US/CA detection. Same batch task workflow as other checkers.

Upload detection file — example:

curl --location 'https://api.numberchecker.ai/v1/tasks' \
--header 'X-API-Key: API-KEY' \
--form 'file=@"./numbers.txt"' \
--form 'task_type="usaCarrier"'

Check task status — example:

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

Response after upload succeeds

{
    "task_id": "d4g8o46p2jvh04o9uolg",
    "status": "pending",
    "total": 2049,
    "estimated_amount": {
        "amount": "0.500000",
        "currency": "USD"
    },
    "message": "Task created successfully",
    "created_at": "2026-04-28T11:58:08.916446594Z"
}

Response while processing

{
    "created_at": "2026-04-28T08:27:09.933Z",
    "updated_at": "2026-04-28T08:27:10.241Z",
    "task_id": "d4g24nep2jvh04o9uoh0",
    "user_id": "wfi7wGPS4B4PdtTMox5Y",
    "status": "processing",
    "total": 2049,
    "success": 1024,
    "failure": 0
}

Response when finished (exported)

{
    "created_at": "2026-04-28T08:27:09.933Z",
    "updated_at": "2026-04-28T08:27:10.241Z",
    "task_id": "d4g24nep2jvh04o9uoh0",
    "user_id": "wfi7wGPS4B4PdtTMox5Y",
    "status": "exported",
    "total": 2049,
    "success": 2049,
    "failure": 0,
    "result_url": "https://example-link-to-results.zip",
    "actual_amount": {
      "amount": "2.000000",
      "currency": "USD"
    }
}

Upload file request URL

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

Upload file request parameters

Parameter	Description
`file`	`file`, one phone number per line (E.164 format)
`task_type`	`string`, set to `usaCarrier`

Check task status request URL

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

Check task status request parameters

Parameter	Description
`task_id`	`string`, Task ID returned from task creation

Result fields

Field	Description
`number`	Phone number in E.164 format
`number_type`	Line type (e.g. mobile, landline, virtual)
`country_code`	Country calling code
`carrier`	Carrier / operator name
`underlying_carrier`	Underlying (host) carrier for virtual numbers
`region`	Region / state
`city`	City

Response format

Field	Description
`created_at`	Timestamp when task was created
`updated_at`	Timestamp of last task status update
`task_id`	Unique task identifier
`user_id`	User ID
`status`	`pending` · `processing` · `exported` · `failed` (refunded automatically)
`total`	Total phone numbers processed
`success`	Numbers successfully identified
`failure`	Numbers that failed processing
`result_url`	Download URL when `status` is `exported`
`actual_amount`	(Optional) Actual charged amount, returned after the task is settled
`estimated_amount`	(Create response) Estimated amount for the task; the final charge is settled when the task completes

Status codes

Status	Description
`200`	`free`, Request successful (e.g. status query)
`202`	`charge`, Task created successfully; the estimated amount is deducted
`400`	`free`, Bad request: invalid parameters or file format, unsupported task type, or fewer valid entries than the minimum batch size
`401`	`free`, Missing or invalid API key
`402`	`free`, Insufficient account balance
`404`	`free`, Task not found
`413`	`free`, Uploaded file too large
`500`	`free`, Internal server error, retry later