Mapping Asynchronous Task Lifecycle: From Submission to Signal Retrieval
When integrating NumDetect into your CRM or data pipeline, it is essential to treat the workflow as an asynchronous operation. Because bulk phone validation and signal detection involve processing large datasets, the system operates on a task-based lifecycle rather than a real-time request-response model. This runbook outlines how to manage the transition from task submission to result retrieval.
1. Submitting the Bulk Task
All operations begin by submitting a file via POST /api/v1/bulk-tasks. To ensure a successful submission, your file must strictly adhere to the following requirements:
- Format: Use
.txt or .csv files only. XLSX or other spreadsheet formats are not supported.
- Structure: Provide a single column of E.164 formatted numbers (e.g.,
+12025550101). Each line must contain exactly one number.
- Scope: Each task must be limited to a single country or region. Ensure all numbers in the file correspond to the selected ISO country code.
- Volume: Each task must contain between 500 and 500,000 numbers.
Upon submission, the system validates the file. If the file meets these criteria, the task enters the queue and is assigned a unique task ID. Detailed documentation can be found at https://numdetect.com/api-docs.
2. Monitoring Task State Transitions
Once the task is submitted, you must implement a polling mechanism to track its progress. Use GET /api/v1/bulk-tasks/{id} to retrieve the current status of your task. The lifecycle transitions through three primary states:
- processing: The system is currently analyzing your list. During this phase, you should continue to poll the status periodically.
- success: The task has completed. The API response will now include the necessary metadata to trigger your download process.
- failed: An error occurred during processing. Check the task response for details regarding the failure.
3. Retrieving Results
Once the status returns as success, you can proceed to download the structured result file. The output will contain product-specific fields (such as activated for validation tasks or carrier information for global carrier lookups) mapped to the original identifiers.
Implementation Checklist
Takeaway
By treating NumDetect as an asynchronous service, you decouple your application's responsiveness from the heavy lifting of bulk data processing. Always rely on the success state transition before attempting to parse result files, and ensure your integration handles the "unknown" signal state gracefully to maintain high data quality in your downstream CRM or routing logic. For full documentation and pricing, visit https://numdetect.com.
Mapping Asynchronous Task Lifecycle: From Submission to Signal Retrieval
When integrating NumDetect into your CRM or data pipeline, it is essential to treat the workflow as an asynchronous operation. Because bulk phone validation and signal detection involve processing large datasets, the system operates on a task-based lifecycle rather than a real-time request-response model. This runbook outlines how to manage the transition from task submission to result retrieval.
1. Submitting the Bulk Task
All operations begin by submitting a file via
POST /api/v1/bulk-tasks. To ensure a successful submission, your file must strictly adhere to the following requirements:.txtor.csvfiles only. XLSX or other spreadsheet formats are not supported.+12025550101). Each line must contain exactly one number.Upon submission, the system validates the file. If the file meets these criteria, the task enters the queue and is assigned a unique task ID. Detailed documentation can be found at https://numdetect.com/api-docs.
2. Monitoring Task State Transitions
Once the task is submitted, you must implement a polling mechanism to track its progress. Use
GET /api/v1/bulk-tasks/{id}to retrieve the current status of your task. The lifecycle transitions through three primary states:3. Retrieving Results
Once the status returns as
success, you can proceed to download the structured result file. The output will contain product-specific fields (such asactivatedfor validation tasks or carrier information for global carrier lookups) mapped to the original identifiers.Implementation Checklist
+sign.GET /api/v1/bulk-tasks/{id}. Do not flood the endpoint.Takeaway
By treating NumDetect as an asynchronous service, you decouple your application's responsiveness from the heavy lifting of bulk data processing. Always rely on the
successstate transition before attempting to parse result files, and ensure your integration handles the "unknown" signal state gracefully to maintain high data quality in your downstream CRM or routing logic. For full documentation and pricing, visit https://numdetect.com.