Product guidance
The ws_avatar Service Type: Request, Response and Field Reference
A field-level reference for WA Lookup's ws_avatar service type: the synchronous request contract, the response fields, and what avatar and avatar_url carry.
WA Lookup exposes its WhatsApp checks through a single synchronous call, and the service_type value decides which check runs. This is the field-level reference for the ws_avatar variant.
To run a WhatsApp avatar check with WA Lookup, send POST /api/v1/check with the X-API-Key header and a JSON body of {"service_type": "ws_avatar", "identifier": "<E.164 number>"}. The response returns the standard check fields plus an avatar boolean and, when the upstream service supplies one, an avatar_url string.
The request contract
WA Lookup documents one synchronous call, POST /api/v1/check, sent with the X-API-Key header and Content-Type: application/json. The body carries exactly two values: service_type, which selects the check, and identifier, which must be the phone number in E.164 format. Submitting a number in a local format is the most common cause of an avoidable failure, so normalize before you send.
The response fields you always get
Every WA Lookup check response carries id, identifier, registered, transaction_id, status, service_type and charged_amount_micros. The registered field answers whether a WhatsApp account is present for the submitted number. The transaction_id and charged_amount_micros fields are what you keep for reconciliation, since they tie the result back to what was billed.
The two fields ws_avatar adds
Choosing service_type=ws_avatar adds an avatar boolean and an avatar_url string. The avatar boolean reports whether an avatar was detected. The avatar_url string is present only when the upstream service supplies one, so your integration must treat it as optional rather than assuming it accompanies every positive avatar value. An absent avatar_url is a normal outcome, not an error.
Everything arrives in one response
Because the call is synchronous, the registration and avatar fields come back in the same HTTP response as the request. There is no job identifier to store and no status route to poll, which keeps the integration to a single call and a single error path. Code written for a polling API usually has structure that can simply be deleted here.
FAQ
Is avatar_url always present when avatar is true?
No. avatar_url is present only when the upstream service supplies one, so treat it as optional in your data model.
What number format does identifier require?
E.164. Normalizing before submission avoids the most common category of failed checks.
Do I need a second call to get the registration status?
No. ws_avatar returns the registration field alongside the avatar fields in the same response.