Verifying whether a phone number is registered on WhatsApp is a common requirement for streamlining communication workflows. By using the WA Lookup API, you can integrate account-presence signals directly into your application logic. This tutorial walks through the implementation of a synchronous registration check.
Prerequisites
Before starting, ensure you have:
- An active account on WA Lookup.
- An API key generated via your account dashboard.
- Your environment configured to send standard HTTP POST requests.
1. Understanding the Request Structure
The API operates on a synchronous request-response model. When you send a request, the service returns the result in the same HTTP response. All identifiers must be submitted in E.164 format to ensure accurate processing.
To perform a check, send a POST request to the documented endpoint, including your X-API-Key in the header. The request body requires a service_type and an identifier.
2. Choosing Your Service Type
Depending on your needs, you can select from different check types:
-
ws: Confirms if the number is registered on WhatsApp. -
ws_avatar: Confirms registration and retrieves avatar information. -
ws_business: Confirms registration and identifies if the account is a business profile.
3. Implementation Workflow
Step 1: Prepare the Request
Ensure your payload is formatted as JSON. If you are checking a single number, use the single-identifier structure. For larger lists, you can utilize the synchronous batch endpoint, which accepts up to 100 identifiers in a single request.
Step 2: Handle the Response
Because the API is synchronous, your application will receive the result immediately.
-
Successful Checks: The response contains a
dataobject with the registration status and any requested metadata (such as business markers or avatar URLs). - Undetermined Results: If a check cannot be decided, the API returns a non-zero business code. In such cases, the system automatically refunds the balance for that specific check.
Step 3: Integrate with AI Assistants
If you use AI-driven development tools, you can leverage the official MCP Server. It connects to the same infrastructure as the REST API using your existing credentials. It exposes tools for balance queries, single-number checks, and small-batch checks, allowing your AI agents to interact with the service using the same semantics as your backend code.
Best Practices for Reliability
- E.164 Formatting: Always normalize your input phone numbers to E.164 format before submission.
- Concurrency: The API documentation defines specific per-user concurrency and timeout controls. Monitor your application's response handling to ensure it remains within these defined operational boundaries.
- Balance Management: Since checks are balance-based, monitor your usage via the dashboard. Remember that failed or undetermined checks do not consume your balance.
Conclusion
Integrating WhatsApp registration checks allows you to build more responsive communication systems. By focusing on synchronous, E.164-compliant requests, you can ensure your application receives reliable account-presence signals in real-time. For detailed limits and technical specifications, always refer to the official API documentation.
This article was drafted with AI assistance and reviewed before publishing.
