# Acheter et libérer un numéro

L'achat d'un numéro nécessite deux appels : recherchez dans un pays ce qui est en vente, puis commandez celui que vous voulez. Tout ici requiert une clé API avec le scope `numbers`, et le premier achat dans une organisation nécessite une vérification d'identité.

## Rechercher dans un pays

La recherche porte toujours sur un seul pays, donc `country_code` est obligatoire. Affinez-la avec `number_type`, `capabilities`, ou un `prefix` de chiffres nationaux.

**TypeScript**

```typescript
// The search is always country-scoped, so country_code is required.
const page = await bird.numbers.available.list({
  country_code: "GB",
  capabilities: ["sms", "voice"],
});
for (const candidate of page.data) {
  console.log(candidate.number, candidate.number_type);
}
```

Examples: [TypeScript](/fr-fr/documentation/guides/numbers/buying-numbers.ts.md) · [Python](/fr-fr/documentation/guides/numbers/buying-numbers.py.md) · [Go](/fr-fr/documentation/guides/numbers/buying-numbers.go.md) · [PHP](/fr-fr/documentation/guides/numbers/buying-numbers.php.md) · [cURL](/fr-fr/documentation/guides/numbers/buying-numbers.curl.md)

Utilisez l'hôte régional correspondant au préfixe `bk_{region}_` de votre clé : `https://us1.platform.bird.com` ou `https://eu1.platform.bird.com`.

Chaque résultat ne contient que ce dont vous avez besoin pour en choisir un :

```json
{
  "data": [
    {
      "number": "+447700900123",
      "country_code": "GB",
      "number_type": "mobile",
      "capabilities": ["sms", "voice"]
    }
  ],
  "next_cursor": null,
  "prev_cursor": null
}
```

Notre propre inventaire est renvoyé en premier et paginé normalement. La dernière page peut inclure des numéros qu'un opérateur propose en temps réel ; un numéro listé il y a un instant peut donc déjà être pris au moment où vous le commandez.

Pour vérifier qu'un numéro est encore disponible avant de le commander, relisez-le avec [`GET /v1/numbers/available/{number}`](/docs/api/reference/get-available-number). Un `404` signifie qu'il n'est pas actuellement en vente, que l'opérateur l'ait retiré ou que notre propre inventaire l'ait réservé. La revérification utilise la même limite de débit `numbers_availability` que la recherche : ne revérifiez donc que le candidat que vous êtes sur le point de commander, pas chaque résultat.

## Commander le numéro

Transmettez un numéro issu de la recherche à [`POST /v1/numbers/orders`](/docs/api/reference/create-numbers-order). Pour la protection contre les nouvelles tentatives, voir [Idempotency](/docs/guides/idempotency).

**TypeScript**

```typescript
const order = await bird.numbers.orders.create({ number: "+447700900201" });
// Most orders finish inside the request. One that has to wait on a carrier
// comes back without a number_id. Poll it until it is completed or failed.
if (order.status === "completed") {
  console.log("allocated as", order.number_id);
} else {
  console.log("still", order.status, "; poll", order.id);
}
```

Examples: [TypeScript](/fr-fr/documentation/guides/numbers/buying-numbers.ts.md) · [Python](/fr-fr/documentation/guides/numbers/buying-numbers.py.md) · [Go](/fr-fr/documentation/guides/numbers/buying-numbers.go.md) · [PHP](/fr-fr/documentation/guides/numbers/buying-numbers.php.md) · [MCP](/fr-fr/documentation/guides/numbers/buying-numbers.mcp.md) · [cURL](/fr-fr/documentation/guides/numbers/buying-numbers.curl.md)

La plupart des commandes aboutissent dans la requête et répondent `201` avec le numéro déjà à vous :

```json
{
  "id": "nor_01m0da22b0e39anhzyhtw3gzdg",
  "number": "+447700900123",
  "country_code": "GB",
  "number_type": "mobile",
  "status": "completed",
  "number_id": "nda_7eqywfwzxwa1za9n8wp7e1xkr8",
  "failure_reason": null,
  "completed_at": "2026-08-19T15:25:56.479320Z",
  "created_at": "2026-08-19T15:25:56.448051Z",
  "updated_at": "2026-08-19T15:25:56.479320Z"
}
```

`number_id` est l'identifiant pour tout ce qui suit : lire le numéro et le libérer.

## Interroger une commande qui n'a pas abouti

Une commande qui doit attendre un opérateur répond `202` à la place, avec `number_id` encore à `null`. Relisez-la jusqu'à ce que `status` soit `completed` ou `failed`.

**TypeScript**

```typescript
const order = await bird.numbers.orders.get("nor_01krdgeqcxet5s7t44vh8rt9mg");
// failure_reason says what went wrong, and only ever on a failed order.
console.log(order.status, order.failure_reason ?? "");
```

Examples: [TypeScript](/fr-fr/documentation/guides/numbers/buying-numbers.ts.md) · [Python](/fr-fr/documentation/guides/numbers/buying-numbers.py.md) · [Go](/fr-fr/documentation/guides/numbers/buying-numbers.go.md) · [PHP](/fr-fr/documentation/guides/numbers/buying-numbers.php.md) · [MCP](/fr-fr/documentation/guides/numbers/buying-numbers.mcp.md) · [cURL](/fr-fr/documentation/guides/numbers/buying-numbers.curl.md)

Une commande passe par `charging`, `ordering` et `pending` avant de se stabiliser. En cas de `failed`, `failure_reason` indique ce qui a échoué en termes clairs. Des frais d'installation déjà prélevés ne sont pas remboursés : une commande échouée peut donc laisser un montant facturé ; contactez le support si cela se produit.

## Libérer un numéro

La libération arrête la facturation mensuelle et le numéro cesse de fonctionner pour vous. Seul un numéro `dedicated` peut être libéré, et un numéro libéré ne repart pas directement en vente.

**TypeScript**

```typescript
// Releasing stops the monthly charge and the number stops working for you.
// Only a dedicated number can be released; a shared one answers E14002.
await bird.numbers.release("nda_01krdgeqcxet5s7t44vh8rt9mg");
```

Examples: [TypeScript](/fr-fr/documentation/guides/numbers/buying-numbers.ts.md) · [Python](/fr-fr/documentation/guides/numbers/buying-numbers.py.md) · [Go](/fr-fr/documentation/guides/numbers/buying-numbers.go.md) · [PHP](/fr-fr/documentation/guides/numbers/buying-numbers.php.md) · [MCP](/fr-fr/documentation/guides/numbers/buying-numbers.mcp.md) · [cURL](/fr-fr/documentation/guides/numbers/buying-numbers.curl.md)

Une libération réussie répond `204` sans corps.

## Quand une commande est refusée

Quatre refus couvrent la quasi-totalité des achats échoués.

`402` avec [`E03000`](/docs/api/errors/E03000) signifie que le portefeuille ne peut pas couvrir le numéro. Rechargez-le et commandez à nouveau. Aucune commande n'est créée, donc rien n'est facturé.

`412` signifie que l'organisation n'a pas complété la vérification d'identité requise pour un premier achat. Complétez-la, puis réessayez.

`409` avec [`E14000`](/docs/api/errors/E14000) signifie que le numéro a disparu pendant que vous le choisissiez. Relancez une recherche et choisissez-en un autre.

`409` avec [`E14001`](/docs/api/errors/E14001) signifie que trop de vos commandes sont déjà en cours. Attendez qu'une aboutisse, puis commandez à nouveau.

## Étapes suivantes

- [Vue d'ensemble des numéros](/docs/guides/numbers/overview) explique la signification des champs d'un numéro.
- [Référence API des numéros](/docs/api/reference/create-numbers-order) documente chaque opération et chaque champ.
- [Idempotence](/docs/guides/idempotency) explique comment les clés sécurisent une commande réessayée.

## Related resources

- [What is a virtual phone number (VMN)?](/explained/numbers/what-is-a-virtual-phone-number) (answer)
- [SMS numbers](/sms-api/features/numbers) (product)
- [Number types](/docs/guides/numbers/number-types) (docs)

[Get an implementation brief](/learn/workspace?topic=phone-numbers)