WhatsApp Lookup API: Realtime Registration Checks Explained

Learn how the WhatsApp lookup API handles synchronous realtime registration checks, response parsing, and high-volume workflows for clean communication pipelines.

The WA Lookup API provides synchronous realtime verification to confirm whether a phone number is registered on WhatsApp at the moment of the query. By querying dedicated REST endpoints, teams receive immediate account-presence signals within the initiating HTTP response. This architecture supports single-number checks and synchronous multi requests, helping organizations clean routing queues, protect delivery workflows, and avoid messaging unallocated numbers.

Understanding WhatsApp Registration Signals

A registration check evaluates whether a specific identifier maintains an account on the platform at check time. This platform-presence signal provides technical reachability context before initiating communication.

Phone numbers must follow the international public telecommunication format described in ITU-T Recommendation E.164, which mandates country codes and limits lengths to 15 digits. Evaluating numbers in E.164 structure standardizes input data across international systems.

From an operational perspective, registration data informs audience routing rather than establishing identity, line ownership, or recipient consent. Organizations conducting commercial outreach must maintain separate opt-in consent records to comply with the WhatsApp Business Messaging Policy. Aligning account-presence checks with the data minimization requirements in GDPR Article 5 (Regulation (EU) 2016/679) ensures systems process only the technical reachability indicators necessary for delivery workflows.

Synchronous Realtime Verification Workflows

The WhatsApp lookup API exposes synchronous endpoints designed for immediate, in-line decision pipelines. Because these endpoints operate synchronously, the initiating HTTP request receives verification attributes directly in the response payload without requiring secondary polling cycles.

Single-Number Check

For transactional events such as registration forms or single-lead intakes, the integration calls POST /api/v1/check using the X-API-Key authentication header. The request submits an E.164 phone string and selects the target service type.

Synchronous Multi-Check

When workflows require validating smaller queues simultaneously, POST /api/v1/batch-check accepts up to 100 phone numbers in a single call. The endpoint evaluates the full batch synchronously and returns the unified set of results in the initiating response.

Developers managing request volume should review the official documentation for per-user concurrency and timeout parameters, as the platform manages capacity through concurrency controls rather than fixed per-minute request ceilings.

Comparing Realtime Service Check Types

The lookup API structures registration queries into three specific realtime service types to support different risk and enrichment requirements.

Selecting ws provides the core reachability indicator. For workflows requiring profile enrichment, ws_avatar appends avatar availability and the hosted image link when accessible. The ws_business option identifies whether the registered phone operates on the WhatsApp Business platform, supporting segmentation between consumer and commercial accounts.

Interpreting Status Codes and Balance Consumption

Public API responses format completed checks using standard envelope fields containing code, msg, and data. Correctly parsing decided outcomes versus service errors is critical for reliable data pipelines.

A completed check produces a success response code with data.registered set to true or false. Both decided true and decided false records represent completed lookups and consume balance accordingly.

An undetermined state or upstream service interruption returns a non-zero business code rather than a registered=false value. Downstream systems should isolate non-zero codes for retry logic instead of treating them as unallocated phone numbers. Registered accounts can contact support to receive 100 free checks to validate response handling across development environments.

Asynchronous Bulk Tasks for List Processing

While the synchronous endpoints handle live customer interactions, large data migrations require an asynchronous workflow. For file-based validation, teams use POST /api/v1/bulk-tasks to submit datasets and GET /api/v1/bulk-tasks/{id} to track processing progress.

Bulk task files must be submitted as TXT or CSV documents containing one phone number per line. The file must focus on a single country destination, as lists with 10% or more numbers outside the target country trigger precheck rejection. Per-product file limits apply, and teams should consult the official documentation for current file sizing rules.

Regional coverage also differs between workflows. Realtime single-number checks support numbers from mainland China (+86), Hong Kong (+852), and Macau (+853) at lower volumes, whereas asynchronous bulk file tasks exclude those destinations. Taiwan coverage remains unconfirmed across all processing modes.

FAQ

How do realtime synchronous checks differ from asynchronous bulk tasks?

Realtime checks submit numbers directly to POST /api/v1/check or POST /api/v1/batch-check and deliver results immediately in the same HTTP response. Asynchronous bulk tasks accept formatted files via POST /api/v1/bulk-tasks, run in the background as a task, and generate a downloadable result CSV upon processing completion.

How does the API handle charges for undetermined checks?

Both registered and unregistered completed evaluations incur standard check usage. In contrast, an undetermined or service-error outcome returns a non-zero status code rather than a false result, and failed checks do not consume balance.

Learn More

Choose the product information that fits the next step in your workflow.

• View the product documentation →
• Talk to the team →