A clean list is the start of the next campaign. Check validity and activation signals to find records worth reviewing, then feed the structured result into list cleaning, CRM updates and pre-outreach checks so every action starts with clearer data.
This repository covers the asynchronous, file-based product number_validation_batch. Submit a file, keep the returned task ID, poll it, then use the result URL after success. It is separate from synchronous /api/v1/check and /api/v1/batch-check integrations.
- Product: https://numdetect.com/products/number_validation_batch
- API documentation: https://numdetect.com/api-docs
- API base URL:
https://numdetect.com - Authentication:
X-API-Key - Get an API key: https://numdetect.com/register?utm_source=github&utm_medium=referral&utm_campaign=numdetect_phone-bulk-validation-api
- Registration filtering
- List cleaning
- CRM hygiene
Upload a .txt or one-column .csv file with 500–500,000 valid phone entries. Use a single-country list of international numbers with an explicit country code. country selects that country; it does not add missing country codes. Invalid, missing-country-code, other-country and duplicate lines are counted separately during preprocessing.
Send service_type and, for phone products, country before file in the multipart body. The request field is service_type; the response still calls the selected product data.product.
curl -X POST 'https://numdetect.com/api/v1/bulk-tasks' \
-H 'X-API-Key: YOUR_API_KEY' \
-F 'service_type=number_validation_batch' \
-F 'country=US' \
-F 'file=@numbers.txt'For a retry of the same submission, use the same previously chosen Idempotency-Key header (up to 128 characters). Do not automatically resubmit after a timeout: the original request may already have created a task.
The included numbers.txt is a tiny format fixture, not a production-sized list. Supply an authorized file that meets the product minimum; do not pad it with duplicates or invented identifiers. Example clients accept FILE to select your file.
curl -fsS 'https://numdetect.com/api/v1/bulk-tasks/TASK_ID' \
-H 'X-API-Key: YOUR_API_KEY'Read the code, then data.status. Poll no more often than once every 30 seconds:
processing: keep the task ID and wait.preparing=truemeans input preprocessing is not complete;totalis preliminary.success: finalsuccess_cntandfailure_cntare available. Useresult_urlto download the result. If the link is temporarily absent, query this task again after 30 seconds; do not submit a replacement task.failed: reportreason/reason_detailand stop polling. An HTTP 200 containingdata.status=failedis a failed task.
The API does not return a progress percentage or pricing/reservation quote. Request fields, response fields, and examples are specified in openapi.yaml.
The current brand-side export uses these columns, in this order. Preserve their names when parsing the result; do not substitute upstream CSV headers.
| Column | Example | Meaning |
|---|---|---|
identifier |
12345678900 |
Submitted identifier, used to join the result to the input. Phone identifiers include their country code. |
activated |
true |
The determined positive/negative signal for this product; interpret it in the product context. |
These are point-in-time product signals. Empty or unknown values are not proof of a negative fact; avatar attributes are image-derived estimates, not verified facts about a person.
| Contract | Value |
|---|---|
service_type |
number_validation_batch |
| Input | phone |
| Valid entries per task | 500–500,000 |
| Country | Required; one country per task |
| Poll interval | At least 30 seconds |
| File formats | .txt, one-column .csv |
The input amount is reserved on submission. Settlement charges checked entries and returns the remainder; failed tasks are refunded. See current pricing rather than assuming a fixed price. GET /api/v1/balance returns USD micros in data.balance_micros.
40000/40001 cover invalid requests or inputs; 40100 is an invalid key; 40200 is insufficient balance; 42900/42901 are rate/concurrency limits; 50300 is temporary maintenance. Honor Retry-After. Do not treat a request error or undetermined item as a determined negative result.
Run from the repository root; use the commands and prerequisites in each language README.
| Language | Example | Coverage |
|---|---|---|
| Python | examples/python | Submit and poll; print result metadata / URL |
| Node.js | examples/nodejs | Submit and poll; print result metadata / URL |
| Shell | examples/shell | Submit and poll; print result metadata / URL |
| Go | examples/go | Submit; prints the task ID in its JSON response |
| PHP | examples/php | Submit; prints the task ID in its JSON response |
| Java | examples/java | Query one existing task ID |
| C# | examples/csharp | Query one existing task ID |
Read the key from NUMDETECT_API_KEY on a trusted server. API_BASE_URL is available for a trusted development/mock endpoint; never send a production key to an untrusted override. Do not expose keys in browser code or commit them.
- Product: https://numdetect.com/products/number_validation_batch
- Documentation: https://numdetect.com/api-docs
- Registration: https://numdetect.com/register?utm_source=github&utm_medium=referral&utm_campaign=numdetect_phone-bulk-validation-api
- Pricing: https://numdetect.com/pricing
- OpenAPI: openapi.yaml
- Sample code license: MIT
Process only identifiers you are authorized to use. Third-party trademarks do not imply affiliation or endorsement.
Last reviewed: 2026-10-30 · Maintained by NumDetect.