How to Integrate a Bulk Number Detection API: A 6-Step Guide

How to integrate a bulk number detection API? The answer is a six-step pipeline: "Authentication—E.164 normalization submission—Polling/callback for results—Backoff retry—Three-tier storage," and the result fields must retain the "unknown" tier. In May 2026, Telegram's official documentation updated the description of contacts.resolvePhone: when a number is unregistered or the user has enabled the "find by phone number" privacy restriction, the same PHONE_NOT_OCCUPIED status is returned. This means that if the API was originally designed with only boolean values, privacy-blocked users would be permanently mislabeled as invalid.

A complete integration of a bulk number detection API follows these six steps: authentication preparation, E.164 normalization submission, polling for results, webhook callback for results, backoff retry, and three-tier storage. The order must not be changed, and field design cannot be omitted. This article breaks down each of the six steps with engineering practices you can copy directly. Troubleshooting content is retained in later sections.

First, Determine Integration Mode: Web Batch Run vs. Bulk Number Detection API

Before writing code, think clearly: which type of need are you? For one-time, low-frequency, and a few thousand records, using the web batch run is more cost-effective; you need to periodically incremental clean, automatically write back results to CRM, or embed cleaning operations into existing data pipelines, then it's worth integrating the bulk number detection API. The judgment is simple: check whether the cleaning operation requires automation.

Step 1 Authentication and Environment Preparation: Key Management, Separating Test and Production Batches

Keys should not enter the codebase; use environment variables or a key management service for injection. Use different credentials or different tags for test and production batches to avoid polluting production statistics with joint debugging data. Before running the full volume, first use 10 known result numbers to clear the pipeline, confirming that authentication, encoding, and timeout configurations are correct. These 10 are the foundation for verifying everything else; don't skip them.

Step 2 Submit Tasks: E.164 Normalization Must Be Completed Before Calling

Normalization and deduplication are the responsibility of the caller, not the API. First add country codes, remove spaces and parentheses, standardize to E.164 format, deduplicate based on normalized values, then submit. Submitting dirty data directly will waste quota and pollute result statistics.

How to set batch size? Bigger is not always better. Weigh based on single batch processing time, failure retry cost, and memory usage. For large CSV files, read in chunks by line stream, each chunk a task. Here we recommend a RESTful API like NexCheck—it publicly supports batch submission and can be placed in the pipeline position "after normalization, before CRM write-back." Note: different platforms have different format requirements, and the article Number Registration Status Detection explains the details of normalization.

Step 3 Getting Results Part One: Is the Number Detection API Synchronous or Asynchronous?

Batch detection is inherently asynchronous: submit and get a task ID, results are produced later. Correct polling: first wait a base interval before checking, increase the interval with retry count, set a total timeout and maximum number of polls, and handle terminal and non-terminal states separately. A 1-second infinite polling loop will not only slow down your own system but also hit the other side's rate limit.

Step 4 Getting Results Part Two: How to Integrate Webhook Callbacks

Four things on the callback side: the receiving endpoint must be publicly reachable and return success as quickly as possible; verify the callback signature or key before trusting content; consume idempotently by task ID (duplicate callbacks are written to the database only once); callbacks may be lost, so use a scheduled reconciliation task as a fallback to pull results.

Troubleshooting callback not received: check if the endpoint is reachable, if the firewall or reverse proxy is blocking, if the return code is non-2xx causing the other party to judge failure, if signature verification incorrectly discards normal callbacks. NexCheck's RESTful API publicly supports both real-time query and webhook callback for retrieving results; you can choose based on task scale without needing to build an additional adapter layer. Its unified interface covers 100+ platforms such as WhatsApp, Telegram, LINE, and Zalo, reducing the cost of writing separate adapters and format conversions for each platform. For multi-platform status differences, refer to Multi-platform Number Detection.

Step 5 Failure Handling: What to Do When the Number Detection API Returns 429

The correct response to 429 and various timeouts is not immediate resending, but exponential backoff with random jitter, distinguishing between retryable and non-retryable errors, and capping the number of retries. This is an industry-wide common constraint. As supporting evidence, WhatsApp Cloud API returns error code 130429 when rate limited on the sending side, and 131056 (Pair Rate Limit) for sudden per-user over-limit; the official design requires backoff retry. This is a sending-side metric, not a detection API metric, but it shows that any API call with quotas must be throttled per batch.

For idempotency keys: generate an idempotency key from "batch content hash + business batch number" and register it locally; use the same key on retries to avoid duplicate consumption after network timeouts. A client-side registration table is more reliable than relying solely on the server.

Step 6 Result Storage: Why Fields Must Be Three-Tier Instead of Boolean

This is the core engineering conclusion of this article. Take Telegram's contacts.resolvePhone as an example: when a number is unregistered or the user has enabled the "find by phone number" privacy restriction, the same status is returned. Simply storing as binary "registered/unregistered" will permanently mislabel privacy-blocked users as invalid. Therefore, the result table must have three tiers: "registered / miss / unknown," and retain the original return status for future review. This directly determines whether you can safely perform list trimming downstream.

Field Design for Writing Results Back to CRM: Status Column, Timestamp, Batch Number

Here is a field scheme you can copy directly:

Must be split by platform, not merged into "reachable or not." Valid format, carrier reachable, platform registered, account active, and user authorized are five different things; they cannot be mixed in a field. They each correspond to different judgment sources: valid format comes from E.164 validation; carrier reachable from number range or HLR layer; platform registered from the detection API; account active from behavioral data; user authorized from opt-in records. The detection API covers only the "platform registered" layer; the other four layers must be provided by their respective systems or data sources, and should not be mixed into the same field.

Post-Integration Self-Check List: Small Batch Test, Sample Review, Callback Replay Test

Checklist to check before going live:

• Run a small batch first and manually sample-review some "miss" results
• Observe the rate limit curve to confirm reasonable batch size and concurrency
• Actively replay a callback to verify idempotent consumption
• Disconnect the callback endpoint to verify the fallback reconciliation can fill gaps
• Confirm the key rotation process works

Common Error Troubleshooting: Task Stuck Pending, Duplicate Callbacks, Results Inconsistent with Web Interface

Task stuck pending for a long time: first confirm if submission succeeded, if the batch is too large, or if the queue is backlogged. Duplicate callbacks: indicates idempotent consumption is not done, not a bug on the other side. Results inconsistent with web interface: first align detection time and normalization method. Detection shows registered but cannot send: registration status is not equal to delivery eligibility; authorization and template quality are other constraints; detection results cannot replace opt-in.

FAQ

Is the number detection API synchronous or asynchronous?

Asynchronous. You submit and get a task ID; results are produced later, requiring polling or webhook to retrieve. Design accordingly, don't expect synchronous returns.

How many numbers can I submit to the detection API at once?

Determined by API documentation and actual testing. It's recommended to start with a small batch, observe processing time and rate limit curve, then decide batch size; don't submit everything at once.

What should I do when the number detection API returns 429?

Use exponential backoff with random jitter, distinguish retryable and non-retryable errors, and cap retries. Also check batch size and concurrency, and reduce submission frequency.

Will resubmitting the same batch of numbers incur duplicate charges?

Billing rules depend on the service provider's documentation. On the engineering side, register idempotency keys locally, carry the same key on retries, and verify usage records during small batch tests to confirm if deduplication is applied.

How to upload a large CSV number file in batches?

Read in chunks by line stream, each chunk a task. Determine batch size based on memory and failure retry cost; don't load the entire file at once.

How to write back detection results to CRM fields?

Store status per platform in separate columns, add timestamp and batch number, and retain raw return codes. Use three-tier field values, not booleans.