Tutorial: Building a Synchronous WhatsApp Verification Layer with Node.js

When building communication platforms, developers often struggle with data hygiene. Sending messages to numbers that aren't registered on WhatsApp wastes resources and degrades your sender reputation. While basic regex validation can catch formatting errors, it cannot confirm if a number is actually active on the platform.

In this tutorial, we will build a synchronous verification layer using Node.js that integrates with the WA Lookup API to validate phone numbers in real-time.

Understanding the Synchronous Contract

Unlike systems that require polling or webhooks, this API operates on a synchronous request-response cycle. When you submit a request, the platform processes the check and returns the result in the same HTTP response. This simplifies your application architecture significantly—you don't need to manage state machines or callback endpoints.

Prerequisites

• E.164 Formatting: All numbers must be provided in E.164 format (e.g., [phone]).
• API Key: You can generate your key via the WA Lookup dashboard.
• Service Types: You must choose the appropriate service_type based on your needs:
  • ws: Basic registration check.
  • ws_avatar: Registration plus avatar availability and URL.
  • ws_business: Registration plus business account identification.

Implementation Steps

1. Configure the Request

Your application needs to send a POST request to /api/v1/check. The request must include your X-API-Key header and a JSON body specifying the target number and the desired service.

2. The Integration Pattern

Using axios or fetch, you can implement a clean wrapper for your service layer:

async function verifyWhatsAppNumber(phoneNumber, type = 'ws') {
 const response = await fetch('https://walookup.com/api/v1/check', {
 method: 'POST',
 headers: {
 'Content-Type': 'application/json',
 'X-API-Key': process.env.WA_API_KEY
 },
 body: JSON.stringify({
 service_type: type,
 identifier: phoneNumber
 })
 });

 return await response.json();
}

3. Handling the Response

Every successful check returns a consistent schema including id, identifier, registered, transaction_id, status, service_type, and charged_amount_micros.

• If you use ws_avatar, the response will additionally contain avatar (boolean) and avatar_url (if available).
• If you use ws_business, the response will include the business (boolean) flag.

Important Considerations for Production

• Billing: You are only charged for successful checks. If a check fails or returns an undetermined result, the system automatically refunds the balance.
• Scope of Data: A "registered" result confirms the account's presence on the platform at the time of the check. It does not provide information regarding online status, last seen, or message history.
• Compliance: Always remember that a successful registration check is not proof of consent. You must ensure you have obtained the necessary permissions to contact the user according to local regulations and platform policies.

Conclusion

By integrating a synchronous verification layer, you can clean your contact lists and enrich your CRM data before initiating any communication. This approach keeps your backend logic simple while ensuring your outreach is targeted at active WhatsApp users. For more details on managing your API keys and reviewing your 7-day usage trends, visit the WA Lookup documentation.

This article was drafted with AI assistance and reviewed before publishing.