A number you have already bought is the expensive place to discover that WhatsApp will not take it. WhatsApp refuses any number already registered on it, including a number registered to the consumer WhatsApp app years ago by someone who no longer works at the company, and refuses some numbers it cannot serve at all. Neither refusal is visible from the number itself.
So the check runs before the purchase, against WhatsApp, on the specific number you mean to buy.
What does the precheck actually ask?
It asks WhatsApp, about one number, whether that number can be connected.
The request carries a single field, phone_number, in E.164 format. The number does not have to be one you already hold with us, which is the whole point: you are asking about a number you are considering.
Two properties of the check matter more than its shape.
It is a write rather than a lookup. The number is sent to WhatsApp and WhatsApp answers for it. Nothing is connected to your workspace as a result, and nothing is reserved for you. Because a real request leaves for WhatsApp each time, the check is meant for the number you intend to buy rather than for sweeping a list of candidates. Reuse an Idempotency-Key inside the idempotency window, three hours by default, and you get the stored answer back instead of asking WhatsApp again; the response says so with an Idempotency-Replay header. Once the window closes, the same key asks WhatsApp afresh.
The answer describes a moment. A number that is available when you ask can be registered by someone else before you connect it. The check narrows the risk of buying a dead number, and it does not hold the number for you.
What do the two answers mean?
The outcome is one of exactly two values, and the second one is deliberately blunt.
availablemeans nothing prevents connecting that number today.unavailablemeans WhatsApp refuses it.
An unavailable number is refused for one of two reasons: it is already in use on WhatsApp, or it is a number WhatsApp cannot serve. The two cannot be told apart. WhatsApp does not say which, so neither do we, and any provider that shows you a specific reason here is inferring it.
For a buying decision the ambiguity costs nothing, because both reasons lead to the same move: skip the number and check the next one. The ambiguity matters when the number is one you already own and were counting on, and that case is worth its own section below.
Where does the check sit in buying a number?
Four steps, in this order:
- Search one country.
bird numbers available list --country-code USreturns the numbers on sale there, and--country-codeis required. What comes back is a search hit rather than a reservation. - Re-check the one you picked with
bird numbers available get. A404means the carrier has sold it since your search, so search again instead of ordering it. - Ask WhatsApp about that number with the precheck.
- Order it with
bird numbers orders create, only if the precheck answeredavailable.
Reversing steps 3 and 4 is the mistake the check exists to prevent. A number bought and then refused by WhatsApp is a number you own and cannot use as a WhatsApp sender.
Two conditions sit outside the sequence. Ordering any number needs your organization's verification steps finished, and an order is refused while one is outstanding; those are completed in the dashboard and nowhere else. And an order a carrier has to provision comes back pending, so the number is yours only once the order settles.
What if the number is already mine?
Then the check is diagnosis rather than a purchase decision, and the unavailable ambiguity starts to matter.
The common case is a number already registered on WhatsApp, usually on the consumer app. That registration has to be released from the account holding it before the number can be connected to a business account. It is not something a provider can clear on your behalf, because the account is not ours.
Worth knowing before you get here: a WhatsApp sender does not have to be a number you own. A Bird-managed number needs no setup of this kind, and connecting a number of your own is the path that runs through this check. Which of the two you have decides whether the question arises at all, and WhatsApp phone numbers covers both.
How do I run it?
On the command line, one number per call:
bird whatsapp numbers precheck +31612345678Add --example to print the request body without credentials, or --dry-run to see the resolved request without sending it. --response-schema prints the fields that come back.
The underlying endpoint is POST /v1/whatsapp/numbers/precheck, and it needs a token with write access to WhatsApp management. The operation is on the command line and on the MCP server, so an agent holding your credentials can run the same check on the one number it is about to buy. Keep it to that number. Each check registers the number with WhatsApp on our side, WhatsApp publishes no way to delete such an entry, and an unverified one clears on its own only after 90 days. Sweeping a shortlist leaves an entry behind for every number you did not buy. The command reference carries the flags in full.