cURL request
POST /api/v1/bulk-taskscurl -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]Global carrier lookup
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.
An add-on for whole large lists — for a handful of numbers the realtime check answers in the same request. Realtime check →
Two steps: submit the file, then check the task
Submitting returns a task id right away; check the task by that id and, once it succeeds, the response carries the result file download link. Each request is shown with its own response.
1. Submit the file
The task id comes back straight away with preparing set to true while the file is prepared in the background: invalid lines, duplicates and — for number tasks — numbers without a country code or from another country are removed and not charged. Balance is reserved for the submitted lines and settled on completion; the difference is refunded.
Response: task created
200 OK{
"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"
}
}2. Check the task
Poll by task id. Once preparation finishes, submitted_lines = total + invalid_cnt + no_code_cnt + other_country_cnt + duplicate_cnt, where total is what is checked and charged. A successful response carries the success and failure counts and the result file download link; a task refused during preparation is failed with reason_detail and refunded in full.
cURL request
GET /api/v1/bulk-tasks/{id}curl "https://api.carrierlookup.online/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
-H "X-API-Key: sk_your_api_key"Response: task finished
200 OK{
"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"
}
}What happens to a bulk task
Bulk is not realtime made bigger — it is submit once, run in the background, collect later. You do not need to keep the page open; task state and results stay in your dashboard.
01Upload the file
A .txt or .csv with one number per line. It is streamed straight through; nothing is written to disk.
02Precheck and reserve
Obvious problems (an empty file, the wrong format, too few lines) are rejected on upload. Balance is then reserved and the file is prepared in the background: duplicate and invalid lines are removed and the country rule is checked. A file that fails there ends as a failed task, refunded in full; otherwise only the remaining lines are checked, and the task is settled on completion.
03Run in the background
The task runs on its own — close the page if you like. A failure is reported straight away and fully refunded.
04Download the result
Collect the file from the bulk check page. You pay only for numbers that actually returned a result; the difference is refunded.
Columns in the result file
The download is a single CSV file with the full result table.
Result file columns
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.
When to reach for this one
List segmentation
Organise a full number list by original carrier, line type and allocation country or region in a downloadable result file.
Routing cost review
Use carrier and region columns to compare internal routing, procurement or cost records without checking numbers one by one.
Database hygiene
Find number records missing an original carrier, region or city and create a list for completion and human review. Separate empty, incomplete and inconsistent records so they do not enter later analysis unnoticed.
Suggested workflow: mark records for review, export the list for data completion, then write it back or run the lookup again.
What is the bulk Global carrier lookup?
Bulk carrier lookup is the file version of the realtime carrier lookup, built for lists from a thousand numbers upward: upload a file, the task runs in the background, and you download one result CSV with the same fields for every number. Every number must include its country code, and all numbers in one file must belong to the country you pick at upload; numbers without a country code or from another country are left out and not charged.
Limits of this product
- It describes the network a number was originally allocated to. It does not follow number portability, so it is not necessarily the carrier serving the number today.
- It is not a reachability check and not identity verification: it does not say whether the number is in service, nor who owns it.
- Nothing is sent to the numbers in the file — the lookup runs against allocation data.
- Results reflect the allocation data at the moment the task ran, and stored results are never refreshed for you. Running the file again does not reveal the carriers numbers were ported to.
- Download links expire. Fetch the file soon after the task finishes; if a link expires, check the task again for a new one.
When bulk is worth it — and when realtime is faster
| Realtime check | Bulk check | |
|---|---|---|
| How many numbers | 1 number per single check; several per multi request — exact caps are in the API docs | A whole large list in one task — the current size range is on the pricing page |
| Getting results | Right away: single and multi-endpoint answer in the same response; the dashboard returns them one by one | Download a result file when the task finishes |
| Country | None to pick — each number carries its own country code, mix freely in one request | One country per task, selected at upload and submitted with the file |
| Result shape | JSON, fields per number | Result file (one CSV with the full table) |
| Typical use | CRM enrichment at intake, agent lookups, routing rules | List segmentation, routing cost review, database hygiene |
About Global carrier lookup
When should I use bulk instead of a realtime check?
Use bulk for a whole large list. For a handful of numbers the realtime check answers in the same request, with no task to schedule.
What happens to invalid numbers in the file?
The precheck drops malformed lines, so they never enter the billable count. Of the numbers that remain, any the upstream cannot resolve are not charged either. You pay only for numbers that actually return a result.
How long does a task take?
It depends on the number count and the product. You can close the page after submitting; the task runs in the background and the result waits for you on the bulk check page.
Do I get refunded if it fails?
Yes. A failed task is refunded in full. If the task succeeds but some numbers return nothing, that portion is refunded automatically. The difference between the reserved amount and what was actually charged always comes back.
Create an account to submit a bulk task
Bulk and realtime checks draw on the same balance — nothing extra to enable. Sign up and upload your first file on the bulk check page.