How to Bulk-Verify Phone Numbers from a CSV

Learn how to prepare a CSV of phone numbers in E.164 format and process them using WA Lookup's synchronous API for immediate account-presence signals.

To bulk verify phone numbers from a CSV with WA Lookup, prepare your data by formatting all numbers to the international E.164 standard. Next, process your list by submitting individual, synchronous POST requests to the /api/v1/check endpoint. By selecting the appropriate service type—ws for standard registration, ws_avatar for profile enrichment, or ws_business for business account identification—you receive an immediate account-presence signal in the same HTTP response. Failed or undetermined checks are automatically refunded, helping teams systematically review contact lists and segment audiences based on verified platform registration.

Preparing Your Data for Verification

Before initiating any API requests, your CSV file must be properly formatted. WA Lookup requires all submitted phone numbers to use the E.164 format. This international telephone numbering plan dictates that each number is unique and unambiguous, typically starting with a plus sign followed by the country code and the subscriber number. Standardizing your CSV column to this format reduces errors during the API call and supports accurate processing of the workflow input.

Choosing the Right WhatsApp Check Type

WA Lookup provides three distinct service types through a single endpoint. Selecting the correct type depends on the specific account-presence signal your workflow requires.

Service Type	Scope & Returned Signals
ws	Returns standard platform registration status (registered boolean).
ws_avatar	Checks registration and adds profile enrichment (avatar boolean and avatar_url string, if available).
ws_business	Checks registration and identifies WhatsApp Business accounts (business boolean).
All three products use the same synchronous endpoint; the service_type parameter controls which fields are returned and which balance cost applies.

Executing Your Verification Workflow

Processing a CSV involves iterating through your formatted list and making individual requests to the WA Lookup API. The platform uses a synchronous POST request to the /api/v1/check endpoint. To authenticate, include your API key in the X-API-Key header alongside a Content-Type: application/json header. The JSON body must contain your chosen service_type and the identifier (the E.164 formatted number). Every successful check response carries standard fields, including an id, the identifier, the registered status, a transaction_id, the service_type, and the charged_amount_micros. A registered result confirms account presence at the exact time of the check; it does not check online status, last seen timestamps, or message history.

Managing Costs and Results

WA Lookup operates on a pay-per-check model, meaning your balance is only deducted for completed verifications. If a check fails or returns an undetermined result, the cost is automatically refunded to your account. Teams can monitor their bulk verification progress and costs through the WA Lookup dashboard. The dashboard supports API key management, balance tracking, check history, product-level reporting, recent checks, balance spend, and 7-day trends. New accounts can also claim a $0.10 trial balance to test registration, avatar, and business account checks before processing larger CSV files.

FAQ

Does WA Lookup support asynchronous batch processing?

No, WA Lookup does not support asynchronous batch processing. All checks are synchronous, meaning the result for each submitted phone number is returned immediately in the same HTTP response as the request.

What is the difference between ws, ws_avatar, and ws_business?

The ws service type returns standard platform registration status. The ws_avatar type adds avatar availability and an avatar URL if present. The ws_business type checks registration and identifies if the number is associated with a WhatsApp Business account.

Are failed checks charged to my balance?

No, billing is strictly per check. Any failed or undetermined checks are automatically refunded to your account balance.