Product guidance
One Country, One Product, One Bulk Task
Why every NumDetect bulk task takes a single country and a single product, what the file has to look like, and how to read each signal without over-reading it.
NumDetect is an asynchronous bulk workflow. You upload a file of phone numbers, pick one product and one country, and collect a structured result file once background processing finishes. It is not a real-time single-number lookup, and it does not send messages, place calls, or interact with any account.
Most of the friction people hit is in the first two minutes — file shape and task scope — so it is worth being explicit about both.
The task boundary is one country and one product
Every task carries exactly one product and exactly one ISO country or region code. That is not a UI limitation you can work around by mixing rows; it is the unit of work.
The practical consequence is that a raw export usually has to be split before it is useful. A contact list gathered from several markets becomes one task per market. A list you want scored two different ways becomes two tasks over the same numbers. Planning for that split up front is much less painful than discovering it at submission time.
File requirements are equally fixed: 1,000 to 100,000 valid numbers, TXT or CSV, one number per line. And one exclusion is worth stating plainly rather than letting someone find it the hard way — China mainland numbers are not supported by this bulk workflow, and there is no alternative route for them.
Submitting and polling
POST /api/v1/bulk-tasks submits a task; GET /api/v1/bulk-tasks/{id} retrieves its status. The public states are processing, success and failed — three values, with no intermediate progress percentage to poll for. Build the integration around those three and nothing else, and do not design UI that promises a completion time.
Each product answers one narrow question
Five products sit on the same file format, and the discipline is the same for all of them: each returns a signal, and a signal is not the conclusion someone downstream would like it to be.
Phone Number Validation returns an activated signal. It does not guarantee that a call will connect, an SMS will arrive, a message will be delivered, or an app registration exists — and it says nothing about who owns the number or whether they agreed to be contacted.
Number Activity is an activity signal meant for ranking and segmentation. It is not an online-status indicator, not a timestamp of when someone was last active, and not a frequency measurement. Presenting it as any of those three invents precision the data does not have.
E-commerce Active is likewise a signal, not a record. It is not an order, not a transaction, not proof of spending, and not evidence of purchase intent.
High-Value Users flags potential high value based on premium-device characteristics and recent network activity. It is not proof of income, assets or identity, and it must not be the sole basis for a credit, employment, housing or insurance decision — those are exactly the high-impact uses a probabilistic signal is unfit for.
Global Carrier Detection returns carrier information. It can be affected by number portability and by differences between sources, and it is not a subscriber-identity lookup or a real-time network status.
Reading a result file without inventing conclusions
The shared rule across all five is simple to state and easy to violate under deadline pressure: report the signal you received, keep it labelled as a signal, and let the decision layer above it be explicit about how much weight it carries.
The moment a column named "activity score" is renamed "engaged customer" on its way into a CRM, the caveat is gone and nobody downstream can recover it.