Understand contact identifiers and the target formats used by BSUID-aware WATI APIs.
Overview
BSUID is a WhatsApp business-scoped user identifier. A contact may have a BSUID without a phone number. Availability and accepted identifiers depend on the endpoint and workspace.
Choosing a target
| Endpoint family | Supported formats in the corresponding resolver | Where to obtain the ID |
|---|---|---|
| V3 template send/schedule recipients | Phone, contact ID, or BSUID in target; alternatively use phone_number. Set the channel separately using the request's top-level channel. | Use the phone, contact ID, or BSUID from a contact response or relevant event. BSUID support depends on availability for your workspace. |
| Contact APIs using the contact-and-channel resolver | Phone, contact ID, or BSUID; the resolver can also accept a channel-qualified target. | Use the contact ID from the contact response, not a conversation ID. |
| Conversation APIs using the conversation resolver | Conversation ID, phone, channel:phone, BSUID, or channel:BSUID. BSUID support depends on availability for your workspace. | Use the conversation ID from the relevant conversation response or event, not a contact ID. |
For template recipients, either of these examples provides an identifier:
{"phone_number": "14155552671"}{"target": "US.123456789012345"}The BSUID value is illustrative: use an actual identifier from the same business context, and only when BSUID support is enabled. If both fields are supplied, a non-whitespace target takes precedence. BSUID availability can differ between template and conversation APIs. An unresolved or unavailable BSUID may be omitted from recipient results. If every recipient is invalid, check success and error even when HTTP status is 200.
These formats apply only to endpoints using the named resolver. Check each endpoint reference; do not assume all V1, V2, and V3 endpoints accept the same formats.
Responses and webhooks
Some contact responses and webhook event types expose BSUID-related fields when available. Field names and nullability differ by endpoint and event: use the relevant response schema or webhook reference rather than assuming every payload includes the same identifiers. A BSUID-only contact may have no phone number; consumers that support these contacts should not require a phone number.
Some webhook event types have _bsuid variants. Check the individual event reference and workspace availability before subscribing or changing identity handling.