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=number_activity_batch \
-F country=US \
-F [email protected]Number Activity
Get an activity signal for each number through an asynchronous file task. Combine the true/false results with your own interaction records to review audience groups and follow-up priorities.
This product runs only as an asynchronous file task. Realtime carrier lookup does not return validity or activity signals.
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": "number_activity_batch",
"status": "processing",
"country": "US",
"submitted_lines": 509,
"total": 509,
"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": "number_activity_batch",
"status": "success",
"country": "US",
"submitted_lines": 509,
"total": 500,
"invalid_cnt": 3,
"no_code_cnt": 0,
"other_country_cnt": 0,
"duplicate_cnt": 6,
"preparing": false,
"success_cnt": 495,
"failure_cnt": 5,
"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), used to write the activity result back to a list, customer or lead record. It provides matching and traceability only; it does not include activity time, frequency or interaction details.activated·true— The activity decision returned by this service: true is a match and false an explicit negative. No activity date, count or time window is provided. Interpret it alongside your own interaction records; it does not predict a response.
When to reach for this one
Activity-based segmentation
Write the returned signal into audience tags and review it alongside recent sign-in, purchase or consent status to create groups that are ready for follow-up review.
Join the downloaded identifier to the original record and retain its source for manual review.
Join key: identifier
Reactivation
Before planning reactivation, use the signal and your existing interaction records to set review priorities; a missing signal does not mean a person will never respond.
Keep explicit true, false and missing results separate; leave missing items in a review queue.
Grouping field: activated
Audience planning
Split lists by signal, region or customer stage before setting different content, frequency and contact cadence for each group, then keep measuring your own business results.
Save the result with a task date recorded by your team. Submit a new task when an updated check is needed.
Write-back fields: identifier · activated
What is the bulk Activity check?
Upload a single-country number list and download identifier and activated columns when the task finishes. The signal can support audience grouping, but includes no observation window, last-active date or activity count. A negative result alone does not identify an inactive customer.
Limits of this product
- Read activated according to the selected product: validity/activation or activity. It does not include activity dates or frequency.
- A result does not establish identity or consent, or guarantee that a call or message will connect.
- Results are not refreshed automatically. Submit a new task when you need another check.
About Activity check
What do true, false and a missing result mean?
True is a match for this check and false is an explicit negative. Both are returned decisions; false does not mean execution failed or that the row is free. Treat missing, undetermined and failed results separately using task statistics and final settlement; never fill them with false.
Does this show activity in the last few days or guarantee delivery?
No. Results include no observation window, last-active date, frequency or interaction history, and do not guarantee call or message delivery. Use the signal with your own business records and permission to contact.
Is this available as a realtime check?
This product runs only as an asynchronous file task. Realtime carrier lookup does not return validity or activity signals.
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.
Other bulk products
Global carrier lookupUpload 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.Phone Number ValidationGet a validity or activation signal for each number through an asynchronous file task. True/false results support imported-list review, list cleaning and CRM maintenance.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.