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_validation_batch \
-F country=US \
-F [email protected]Phone Number Validation
Get 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.
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_validation_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_validation_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) and the stable key for matching results to a customer, lead or CRM record. Keep it to trace the source list and write results back in bulk; the field alone does not establish that a number can be contacted.activated·true— Validity/activation decision: true means this check matched; false is an explicit negative. Do not replace missing or failed results with false. This field does not prove identity, permission to contact, or call reachability.
When to reach for this one
Registration-list review
After importing registration or lead lists, review results alongside form data, fraud rules and consent. This asynchronous list check does not replace real-time sign-up code verification.
Join the downloaded identifier to the original record and retain its source for manual review.
Join key: identifier
List cleaning
After export, mark records by activation signal while retaining the original number and source fields; route missing or unusual signals to review instead of deleting business data outright.
Keep explicit true, false and missing results separate; leave missing items in a review queue.
Grouping field: activated
CRM hygiene
Write the check date, product and result into dedicated CRM fields so marketing, service and data teams can work from the same list status in later workflows.
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 Number validation?
Check E.164 numbers in bulk before outreach and return number and activation signals. Use the result to flag records for review, clean lists and maintain CRM data quality; a returned signal does not guarantee a call or message will connect.
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 Number validation
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.Number ActivityGet 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.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.