A carrier can offer a number for sale even when WhatsApp will not accept it. Checking that candidate before ordering avoids paying for a number you cannot connect through the intended setup flow.
How do I run Bird's number precheck?
Use bird whatsapp numbers precheck with the candidate number before buying it.
bird whatsapp numbers precheck +31612345678Supply the number in international format with a leading + and country code. The API request carries it in phone_number. You do not need to own it already.
The endpoint is POST /v1/whatsapp/numbers/precheck. Use a signed-in CLI or MCP grant with whatsapp_management:write, as required by the command reference.
| Flag | What it lets you inspect |
|---|---|
--example | The request body without credentials |
--dry-run | The resolved request without sending it |
--response-schema | The response fields |
An MCP client calls the same operation through whatsapp_numbers_precheck.
What do available and unavailable mean?
available means the check found no obstacle to connecting the number at that moment. unavailable means WhatsApp refused it.
| Outcome | What to do with a purchase candidate |
|---|---|
available | Continue the purchase checks, knowing the result does not reserve the number |
unavailable | Skip that candidate and choose another number |
An unavailable number may already be registered on WhatsApp or may be a number WhatsApp cannot serve. The result does not distinguish those reasons, so do not infer one from the outcome alone.
A request failure is different from an unavailable result. Handle the returned API error before treating the candidate as unsuitable.
Does the check reserve the number?
No. It does not connect the number to your workspace or reserve it for purchase. Someone else can take an available number before you order it.
Check the candidate you intend to buy rather than sweeping a list.
Reuse an Idempotency-Key when retrying the same check. During Bird's three-hour response window, the same key returns the stored answer instead of asking WhatsApp again.
The Idempotency-Replay response header identifies that replay. Once the response window ends, the same key can trigger a fresh check.
Where does the check fit into buying a number?
Check carrier availability and WhatsApp acceptance before placing the number order.
- Search with
bird numbers available list --country-code US. - Recheck the selected candidate with
bird numbers available get. - Run the WhatsApp precheck on that candidate.
- Order only after
available, usingbird numbers orders create.
A 404 from the carrier-availability recheck means you need another candidate. Complete any required organization verification in the dashboard before ordering.
A pending order still needs the carrier to complete provisioning. Wait for the order to settle before relying on the number.
Can I check a number I already own?
No. The precheck is for numbers you plan to buy from Bird. It is not for a number you already hold; it is not for coexistence numbers. Connect a number you already own with Bird's own-number setup.
That setup cannot connect a number while its personal WhatsApp registration remains active. A number on the WhatsApp Business app connects through coexistence. Confirm that the number's status reaches Connected before using it as your branded sender.
Bird-managed senders are a separate option for the managed authentication and utility templates. They do not send your free-form content or receive customer replies into your workspace.
In short
Check before buying.
A number search does not establish WhatsApp compatibility. Run the precheck on the candidate you intend to purchase.
Interpret unavailable without inventing a reason.
The number may already be registered or may be unsupported. The result does not distinguish those cases.
Don't treat the answer as a reservation.
The check does not reserve or connect the number. Order it while the answer is fresh.
Reuse retry keys for the same check.
An idempotency replay returns the stored answer. That answer describes the earlier check, not a fresh availability guarantee.