Ensuring Data Integrity: Validating Input Constraints for NumDetect Bulk Tasks
When integrating with the NumDetect asynchronous bulk workflow, the reliability of your data pipeline depends on strict adherence to input formatting. Because tasks are processed in the background, submitting malformed data or files that fall outside the defined constraints will result in immediate task rejection. This guide outlines how to implement pre-submission validation to ensure your CSV or TXT files are ready for the POST /api/v1/bulk-tasks endpoint.
Validating E.164 Compliance
NumDetect requires that every phone number in your input file adheres to the ITU-T Recommendation E.164 standard. An E.164 number must begin with a country code and contain at most 15 digits.
To prevent ingestion errors, your local validation script should enforce the following:
- Format Check: Ensure each line contains only a single phone number.
- Digit Count: Validate that the string length does not exceed 15 digits after the leading plus sign.
- Exclusion: Note that China mainland numbers are not supported by this workflow. Ensure your filtering logic explicitly excludes these prefixes before generating your upload file.
Enforcing File-Size and Row-Count Requirements
NumDetect requires that each bulk task contains between 500 and 500,000 numbers. Files containing fewer than 500 rows will be declined at the point of upload.
Before initiating a POST request, your application should perform a local count of the valid, E.164-compliant records in your source file. If the count is below the 500-row minimum, the task should be held locally rather than submitted to the API. This prevents unnecessary round-trips and ensures your integration remains efficient.
Implementation Checklist for Local Validation
Before calling the API, confirm your script performs these deterministic checks:
-
Format Verification: Confirm the file is a plain text (TXT) or comma-separated values (CSV) file. Do not attempt to upload XLSX or other spreadsheet formats.
-
Row Count Audit: Verify the total count of valid numbers is $\ge$ 500 and $\le$ 500,000.
-
Sanitization: Strip any whitespace or non-numeric characters from the lines, ensuring only the raw E.164 string remains.
-
Regional Filtering: Ensure the selected ISO country or region code matches the contents of the file, as each task must be associated with one specific region.
Handling Task Lifecycle
Once your file passes these local checks, you can submit the task. Remember that NumDetect is an asynchronous system. After receiving a successful response from POST /api/v1/bulk-tasks, you should transition to using GET /api/v1/bulk-tasks/{id} to poll for the status of your task. The system will return one of three states: processing, success, or failed.
By validating your data locally against these constraints, you reduce the risk of ingestion failures and ensure that your CRM hygiene, audience segmentation, or carrier lookup tasks proceed without interruption. For the latest details on supported parameters and API specifications, consult the official documentation.
Ensuring Data Integrity: Validating Input Constraints for NumDetect Bulk Tasks
When integrating with the NumDetect asynchronous bulk workflow, the reliability of your data pipeline depends on strict adherence to input formatting. Because tasks are processed in the background, submitting malformed data or files that fall outside the defined constraints will result in immediate task rejection. This guide outlines how to implement pre-submission validation to ensure your CSV or TXT files are ready for the
POST /api/v1/bulk-tasksendpoint.Validating E.164 Compliance
NumDetect requires that every phone number in your input file adheres to the ITU-T Recommendation E.164 standard. An E.164 number must begin with a country code and contain at most 15 digits.
To prevent ingestion errors, your local validation script should enforce the following:
Enforcing File-Size and Row-Count Requirements
NumDetect requires that each bulk task contains between 500 and 500,000 numbers. Files containing fewer than 500 rows will be declined at the point of upload.
Before initiating a POST request, your application should perform a local count of the valid, E.164-compliant records in your source file. If the count is below the 500-row minimum, the task should be held locally rather than submitted to the API. This prevents unnecessary round-trips and ensures your integration remains efficient.
Implementation Checklist for Local Validation
Before calling the API, confirm your script performs these deterministic checks:
Handling Task Lifecycle
Once your file passes these local checks, you can submit the task. Remember that NumDetect is an asynchronous system. After receiving a successful response from
POST /api/v1/bulk-tasks, you should transition to usingGET /api/v1/bulk-tasks/{id}to poll for the status of your task. The system will return one of three states:processing,success, orfailed.By validating your data locally against these constraints, you reduce the risk of ingestion failures and ensure that your CRM hygiene, audience segmentation, or carrier lookup tasks proceed without interruption. For the latest details on supported parameters and API specifications, consult the official documentation.