Integrating WA Lookup: Automated CRM Data Hygiene and Account Classification

Learn how to integrate the synchronous WA Lookup API to verify WhatsApp account presence, retrieve avatar details, and classify business accounts for CRM data hygiene.

The WA Lookup API enables CRM systems to perform synchronous verification of WhatsApp account presence. By sending a POST request to the /api/v1/check endpoint with an E.164 formatted phone number, developers can retrieve registration status, avatar availability, or business account classification in the same HTTP response. This data helps maintain CRM hygiene by identifying valid WhatsApp-linked records without requiring asynchronous processing, polling, or webhooks.

Understanding the WA Lookup API Architecture

Integrating account-presence signals into a CRM requires an architecture that supports immediate data routing and decision-making. The WA Lookup API is designed around a single, synchronous endpoint: POST /api/v1/check. When a CRM system or data operations platform submits a request, the API processes the check and delivers the results in the same HTTP response. This synchronous architecture eliminates the engineering overhead associated with asynchronous processing, such as configuring webhooks, managing callback URLs, or implementing polling logic. Developers can integrate the API directly into synchronous workflows, such as lead ingestion forms or real-time data scrubbing pipelines. Every check response carries a standard set of fields to inform internal decisions: id, identifier, registered, transaction_id, status, service_type, and charged_amount_micros. These fields provide the necessary context to update CRM records immediately. It is important to note that these responses are strictly account-presence signals. The API reports the status fields available at the time of the check; it does not check online status, last seen activity, message history, or contact reachability.

Classifying WhatsApp Account Types

To support different CRM data hygiene requirements, the API offers three distinct service types. All three products utilize the same synchronous endpoint, with the service_type parameter controlling which specific fields are returned in the response and which balance cost applies to the transaction.

Comparing Service Types

Technical Implementation and Data Hygiene

Integrating the API into a CRM or data pipeline requires adhering to the documented request contract. The API expects a JSON payload and specific headers to authenticate and process the request successfully. The documented request contract requires a POST request to /api/v1/check. The request must include two headers: X-API-Key containing your authentication key, and Content-Type: application/json. The JSON body must contain exactly two fields:

1. service_type: A string value of ws, ws_avatar, or ws_business.
2. identifier: The phone number to be checked. Crucially, all submitted phone numbers must be formatted according to the E.164 international telephone numbering plan. For example, a US-based number must be submitted as +1234567890. Failing to use the E.164 format may result in parsing errors or undetermined checks. A standard JSON body looks like this: {"service_type": "ws_business", "identifier": "+1234567890"} By standardizing CRM inputs to E.164 and routing them through this synchronous check, developers can automatically flag invalid numbers, segment business users, and maintain a high standard of data hygiene. Because the response is immediate, these checks can be integrated directly into data entry forms, ensuring that only verified account-presence signals are committed to the database.

Dashboard Reporting and Account Management

Managing API usage and monitoring data hygiene operations is handled through the platform dashboard. The dashboard provides comprehensive tools for CRM administrators and developers to track their integration's performance and manage authentication. The dashboard supports full API key management, allowing teams to rotate keys securely. For operational oversight, it provides visibility into the current account balance, detailed check history, and product-level reporting. Administrators can review recent checks, monitor balance spend, and analyze 7-day trends to understand how the API is being utilized across different CRM workflows. The service operates on a strict pay-per-check billing model. The charged_amount_micros field in the API response indicates the cost applied to that specific transaction, which varies based on the service_type selected. To ensure teams only pay for actionable data, any failed or undetermined checks are refunded automatically to the account balance. For developers looking to test the integration and validate the E.164 formatting logic before deploying to production, new accounts can claim a $0.10 trial balance applicable to registration, avatar, and Business account checks.

FAQ

Is the WA Lookup API synchronous or asynchronous?

The WA Lookup API is strictly synchronous. When a request is submitted to the POST /api/v1/check endpoint, the results are returned in the same HTTP response as the request.

Can this API verify if a user is currently online?

No. A registered result reports the WhatsApp status fields available at the time of the check. It acts as an account-presence signal only and does not check online status, last seen timestamps, message history, contact consent, or whether the number can currently be contacted.

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

All three service types use the same synchronous endpoint but return different fields. The ws service type confirms basic WhatsApp registration. The ws_avatar service type returns registration status alongside an avatar boolean and an avatar URL (if supplied by the upstream service). The ws_business service type returns registration status and a boolean indicating if the account uses WhatsApp Business.