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`](/docs/guides/idempotency) 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. - **`available`** means nothing prevents connecting that number today. - **`unavailable`** means 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: 1. Search one country. [`bird numbers available list --country-code US`](/docs/cli/reference/numbers-available-list) returns the numbers on sale there, and `--country-code` is required. What comes back is a search hit rather than a reservation. 2. Re-check the one you picked with [`bird numbers available get`](/docs/cli/reference/numbers-available-get). A `404` means the carrier has sold it since your search, so search again instead of ordering it. 3. Ask WhatsApp about that number with the precheck. 4. Order it with [`bird numbers orders create`](/docs/cli/reference/numbers-orders-create), only if the precheck answered `available`. 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](/products/whatsapp/numbers). 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](/docs/guides/whatsapp/phone-number-setup) covers both. ## How do I run it? On the command line, one number per call: ```bash bird whatsapp numbers precheck +31612345678 ``` Add `--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](/docs/cli/reference/whatsapp-numbers-precheck) carries the flags in full.