How to Prepare a CSV or TXT List for Realtime WhatsApp Number Checks

A practical workflow guide for preparing a CSV or TXT list of phone numbers for realtime WhatsApp checks: E.164 formatting, choosing a service type, and retrieving account-presence signals from the synchronous single and multi endpoints.

WA Lookup checks WhatsApp account presence in real time: send one number to the synchronous check endpoint, or up to 100 numbers to the synchronous multi endpoint POST /api/v1/batch-check, and the completed results return in the initiating HTTP response, with no job to wait for. To run a CSV or TXT list through it, format every identifier strictly in the E.164 international numbering standard, strip non-numeric characters and local prefixes, and pick the service type your workflow needs: ws for basic registration status, ws_avatar to include avatar availability, or ws_business to identify WhatsApp Business accounts. A whole file far beyond one realtime request can also be uploaded as an asynchronous bulk task (upload, wait, download).

Understanding WhatsApp Verification Signals

When preparing a CSV or TXT list for realtime checks, the first step is determining which account-presence signal supports your specific workflow. WA Lookup provides three distinct service types, all accessed through the same synchronous endpoints. The service_type parameter controls which fields are returned in the response.

Basic Registration Check (ws)

The ws service type confirms whether a submitted phone number is currently registered on WhatsApp. This check returns a registered field, providing a straightforward account-presence signal. It informs internal decisions about which numbers in your CSV or TXT file are associated with a WhatsApp account at the time of the check.

Avatar Enrichment Check (ws_avatar)

The ws_avatar service type includes the basic registration check and adds profile enrichment capabilities. In addition to the registered status, this check returns an avatar boolean value indicating avatar availability and an avatar_url string. The URL field is empty when no URL is available. This additional context can be one input alongside other checks when reviewing user profiles.

Business Account Check (ws_business)

The ws_business service type checks WhatsApp registration and identifies whether the account uses WhatsApp Business. It returns a business boolean value. This signal helps teams segment their lists by distinguishing standard accounts from business profiles, supporting more tailored workflow routing.

Preparing Your Data File

The most critical requirement for running a CSV or TXT list through realtime checks is proper data formatting. WA Lookup requires all numbers to be submitted in the E.164 format. E.164 is an international telephone numbering plan that assigns each device a globally unique identifier. To prepare your CSV or TXT file:

1. Include the Country Code: Every number must begin with the appropriate international country code.
2. Remove Formatting Characters: Strip out spaces, dashes, parentheses, and any other non-numeric characters from your list.
3. Omit Leading Zeros: Remove any local trunk prefixes (often a leading zero) that are not part of the international dialing code.

For example, a US-based number should be formatted as a continuous string of digits starting with the country code (e.g., 1). Confirming your entire list adheres to the E.164 standard helps avoid formatting errors during the synchronous check process. A clean, standardized input file is essential for retrieving accurate account-presence signals for every submitted number.

Submitting Your List for Verification

Once your CSV or TXT list is formatted correctly, you can submit the identifiers to the WA Lookup platform. The primary path is synchronous: results are returned in the same HTTP response as the request, rather than being delivered at a later time. For technical teams integrating the service, use POST /api/v1/check for one identifier or the synchronous multi endpoint POST /api/v1/batch-check for up to 100 identifiers. Both requests require an X-API-Key header and a Content-Type: application/json header. The single-check body contains service_type and identifier; the multi body contains service_type and identifiers. Follow the concurrency guidance in the API documentation. A whole CSV or TXT file far beyond one realtime request can also be uploaded as an asynchronous bulk task; you choose the country the numbers belong to when submitting, and the list should be essentially that one country. Failed, timed-out, and undetermined checks do not retain the charge. See the pricing page for current billing details.

Interpreting Your Results

For a completed WhatsApp check, the returned data contains service_type, identifier, and registered; ws_avatar also includes avatar and avatar_url, while ws_business includes business. Internal record, transaction, status, and billing fields are not returned. The registered result reports the WhatsApp status fields available at the exact time of the check. It is important to understand the boundaries of this account-presence signal. Additionally, the verification process does not report live presence, message history, or contact consent. It also does not indicate whether the number can be successfully contacted or if messages will be delivered. The signal simply informs your internal database about platform registration, which can be one input alongside other checks when organizing your CRM or routing records.

FAQ

What is the required format for phone numbers?

All phone numbers must be submitted strictly in the E.164 format. This international numbering plan requires the country code and the removal of all non-numeric characters, spaces, and local leading zeros.

Can I check for WhatsApp Business status across a list?

Yes, by selecting the ws_business service type, you can check both the basic registration status and whether the account uses WhatsApp Business. This returns a specific boolean value indicating business account presence, for a single check or a synchronous multi request alike.

What happens if a check fails?

Failed, timed-out, and undetermined checks do not retain the charge. See the pricing page for current billing details.

Are the verification results delivered asynchronously?

Not on the primary path. The synchronous single and multi endpoints return the completed result in the same HTTP response as the request. An asynchronous bulk task (upload, wait, download) is also available as an add-on for a whole large list, but for everyday checks the synchronous endpoints are the way to go.