---
title: "Gérer vos numéros de téléphone"
description: "Listez et recherchez les numéros attribués à votre espace de travail, étiquetez-les avec un nom et votre propre référence, consultez leur enregistrement vocal, et annulez-les ou libérez-les via API."
canonical: "https://bird.com/fr-fr/documentation/guides/numbers/managing-numbers"
---

# Gérer vos numéros de téléphone

Une fois qu'un numéro est attribué à votre espace de travail, API des numéros vous permet de lister ce que vous détenez, de trouver un numéro par n'importe lequel de ses identifiants, de l'étiqueter avec un nom et votre propre référence, et de l'annuler ou le libérer quand vous n'en avez plus besoin. La lecture nécessite une clé API avec le scope `numbers` en niveau lecture ; modifier, annuler ou libérer un numéro nécessite le niveau écriture.

La page [**Numbers**](https://bird.com/dashboard/w/numbers) dans le tableau de bord affiche les mêmes numéros.

## Lister tous les numéros que vous détenez

[`GET /v1/numbers`](/docs/api/reference/list-workspace-numbers) renvoie les numéros actuellement attribués à votre espace de travail, du plus récent au plus ancien, dédiés et partagés confondus. Chaque page contient 25 numéros, sauf si vous en demandez jusqu'à 100 avec `limit`.

La liste est paginée par curseur. Renvoyez le `next_cursor` d'une page en tant que `starting_after` pour lire la page suivante, et arrêtez quand `next_cursor` vaut `null`. Les SDK suivent le curseur pour vous. Les exemples ci-dessous restreignent la liste à `country_code: "GB"` ; retirez le filtre pour parcourir tous les numéros que vous détenez :

**TypeScript**

```typescript
for await (const allocated of bird.numbers.list({ country_code: "GB" })) {
  console.log(allocated.number, allocated.kind, allocated.status);
}
```

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

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

La liste ne contient pas de total. Pour compter vos numéros, parcourez les pages jusqu'à la fin et comptez les entrées. Passer `include_total` est refusé avec `422` et [`E01029`](/docs/api/errors/E01029).

Chaque entrée porte ses champs `status` et `ownership`. Lorsqu'un pays n'exige aucun justificatif de propriété, `ownership` vaut `null`. La [vue d'ensemble des numéros](/docs/guides/numbers/overview#the-status-of-an-allocated-number) explique la signification de chaque statut. Pour déposer les justificatifs qu'un numéro attend, consultez [Déposer les justificatifs de propriété d'un numéro](/docs/guides/numbers/ownership-paperwork).

Chaque entrée porte aussi `pricing`, ce que votre organisation paie pour le numéro, hors taxes :

- `recurring_price` est votre tarif par `recurring_period`, dans la devise dans laquelle le numéro est facturé. Il s'agit de votre devise de facturation, sauf si l'abonnement du numéro a commencé avant un changement de votre devise de facturation ; un tel numéro conserve la devise de son abonnement, que `currency_code` indique.
- `intervals_per_charge` est le nombre de `recurring_period` facturés par renouvellement. Le montant récurrent hors taxes est `recurring_price` multiplié par `intervals_per_charge`. Un prix fixé pour le numéro couvre toute sa période, donc son `intervals_per_charge` vaut `1`.

`pricing` vaut `null` pour un numéro `shared` et pour un numéro sans abonnement actif. Lorsque l'abonnement d'un numéro n'a aucun prix applicable, ses prix valent `null` avec `pricing.error: null` ; [contactez l'équipe commerciale](/contact-sales) pour obtenir un tarif. Si le prix n'a pas pu être lu, `pricing.error` contient [`E14009`](/docs/api/errors/E14009) et les prix valent `null`. Réessayez [`GET /v1/numbers/{number_id}`](/docs/api/reference/get-workspace-number) avec un backoff exponentiel. Le numéro reste disponible pour la gestion ; ne répétez pas une mise à jour ou une annulation déjà terminée pour actualiser son prix.

Le tableau de bord et API utilisent la même résolution de prix. Un prix fixé conserve ses conditions existantes ; sinon, il s'agit du tarif actuel, qui peut changer avant le renouvellement. Il n'indique pas ce qu'une commande antérieure a facturé. Un numéro dont `releases_at` est défini conserve son `pricing` jusqu'à la libération, et aucun renouvellement ne suit.

## Trouver un numéro dans votre liste

Les filtres de la liste se combinent : un filtre par pays ou par capacité continue de s'appliquer en même temps que les autres.

`number` recherche un numéro quelle que soit la façon dont vos dossiers l'écrivent. `+31612345678` et `0031612345678` correspondent au même numéro. Une écriture nationale telle que `0612345678` n'est résolue que si `country_code` indique le pays :

```bash
curl "https://us1.platform.bird.com/v1/numbers?number=0612345678&country_code=NL" \
  -H "Authorization: Bearer bk_us1_..."
```

Lorsque vous transmettez un numéro complet, ou une écriture nationale avec son `country_code`, sans autre filtre, un tableau `data` vide signifie que le numéro n'est pas attribué à votre espace de travail, ce qui inclut un numéro que vous avez libéré. Une écriture nationale sans `country_code`, par exemple `0612345678` seul, renvoie aussi une liste vide et ne prouve donc pas que le numéro n'est pas le vôtre.

`search` recherche une correspondance partielle dans le numéro, son nom ou sa référence, sans tenir compte de la casse. `reference` renvoie les numéros portant exactement cette référence, en respectant la casse :

```bash
curl "https://us1.platform.bird.com/v1/numbers?reference=STORE-042" \
  -H "Authorization: Bearer bk_us1_..."
```

`prefix` renvoie les numéros qui commencent par les chiffres que vous indiquez, et la signification de ces chiffres dépend de `country_code` :

- Avec `country_code`, les chiffres sont nationaux, comparés juste après l'indicatif. `prefix=6&country_code=NL` renvoie les numéros néerlandais commençant par `+31 6`.
- Sans `country_code`, les chiffres sont comparés depuis le début du numéro complet. `prefix=6` seul renvoie les numéros dont l'indicatif commence par 6, comme les numéros australiens `+61`, et ne trouve donc aucun de vos mobiles néerlandais. Il correspond aussi aux codes courts commençant par ces chiffres.

## Nommer un numéro et définir votre référence

Un numéro porte deux libellés qui vous sont propres. `name` distingue vos numéros les uns des autres, par exemple `Support line`. `reference` contient un identifiant issu de vos propres dossiers, tel qu'un identifiant de client ou de magasin, et n'a pas besoin d'être unique. Les deux s'appliquent aux numéros dédiés et partagés et comptent jusqu'à 100 caractères.

Définissez-les avec [`PATCH /v1/numbers/{number_id}`](/docs/api/reference/update-workspace-number). Un champ que vous omettez conserve sa valeur actuelle, et un champ envoyé avec la valeur `null` est effacé. Les espaces en début et en fin de chaîne sont supprimés.

**TypeScript**

```typescript
const allocated = await bird.numbers.update("nda_01krdgeqcxet5s7t44vh8rt9mg", {
  name: "Support line",
  reference: "STORE-042",
});
console.log(allocated.name, allocated.reference);
```

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

La réponse est `200` avec le numéro mis à jour. Pour effacer la référence et conserver le nom, envoyez la référence comme `null` et omettez le nom :

```bash
curl -X PATCH "https://us1.platform.bird.com/v1/numbers/nda_01krdgeqcxet5s7t44vh8rt9mg" \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -d '{"reference": null}'
```

Pour définir la référence au moment de l'achat du numéro, passez `reference` sur [`POST /v1/numbers/orders`](/docs/api/reference/create-numbers-order). Une commande qui doit attendre un opérateur conserve la référence jusqu'à l'attribution du numéro, et le numéro la porte à partir de ce moment.

## Trouver l'enregistrement vocal qui achemine un numéro

Un numéro qui prend en charge la voix possède deux identifiants. Le `id` sur `GET /v1/numbers` commence par `nda_` pour un numéro dédié et `nal_` pour un numéro partagé, et les opérations sur les numéros l'utilisent. Les opérations vocales, y compris celle qui définit la destination des appels entrants, utilisent l'enregistrement vocal du numéro, dont le `id` commence par `vnu_`. Passer un id `nda_` ou `nal_` à une opération vocale est refusé avec `422`.

Pour passer de l'un à l'autre, recherchez les numéros vocaux par numéro de téléphone. Cela nécessite le scope `voice_management` en lecture :

```bash
curl "https://us1.platform.bird.com/v1/voice/numbers?search=%2B31612345678" \
  -H "Authorization: Bearer bk_us1_..."
```

Le `id` de l'entrée est l'identifiant `vnu_`, et son `provider.number_id` est l'identifiant `nda_` ou `nal_` du même numéro. [Recevoir des appels](/docs/guides/voice/receiving-calls) montre comment acheminer le numéro à partir de là.

L'enregistrement vocal possède un `name` qui lui est propre. Nommer un numéro avec `PATCH /v1/numbers/{number_id}` ne modifie pas le nom de l'enregistrement vocal, et l'inverse est aussi vrai.

## Libérer un numéro

Vous pouvez rendre un numéro dédié de deux façons :

- **À la fin de la période que vous avez payée.** [`DELETE /v1/numbers/{number_id}`](/docs/api/reference/cancel-workspace-number) empêche le renouvellement du numéro. Il continue de fonctionner jusqu'à la fin de la période de facturation en cours, puis il est libéré. La réponse `202` renvoie le numéro avec `releases_at` fixé à cette date, et une nouvelle demande renvoie le même `releases_at`. Une annulation est irréversible. Un numéro sans abonnement associé, par exemple un numéro qui vous a été attribué sans frais, est libéré immédiatement, et la réponse est `200` avec le `status` du numéro défini sur `released`.
- **Immédiatement.** [`POST /v1/numbers/{number_id}/release`](/docs/api/reference/release-workspace-number) libère le numéro sur-le-champ, y compris un numéro déjà programmé pour annulation. Le reste de la période en cours n'est pas remboursé. [Acheter et libérer un numéro](/docs/guides/numbers/buying-numbers#release-a-number) montre l'appel dans chaque SDK.

Tant qu'un paiement de renouvellement pour le numéro est en retard, les deux requêtes répondent `409` jusqu'à ce qu'il soit réglé.

Quelle que soit l'option de libération choisie, envoyez la requête avec un `Idempotency-Key` pour qu'une nouvelle tentative soit sans risque : la même clé rejoue la première réponse avec un en-tête `Idempotency-Replay: true`, tandis qu'une nouvelle requête pour un numéro déjà libéré répond `404` avec [`E01008`](/docs/api/errors/E01008). [Idempotence](/docs/guides/idempotency) explique combien de temps une clé est conservée.

Tant qu'une annulation programmée n'a pas pris effet, le numéro se consulte normalement et porte `releases_at`. Après la libération :

- Le numéro cesse de fonctionner pour vous et son abonnement ne se renouvelle pas.
- `GET /v1/numbers/{number_id}` et l'enregistrement vocal du numéro répondent `404`, et le numéro quitte `GET /v1/numbers`.
- La commande du numéro reste dans [`GET /v1/numbers/orders`](/docs/api/reference/list-numbers-orders), et son `number_id` répond désormais `404`.
- Le numéro entre dans une période de rétention de 30 jours avant de pouvoir être remis en vente ; vous ne pouvez donc pas racheter le même numéro immédiatement.

## Étapes suivantes

- [Recevoir des appels](/docs/guides/voice/receiving-calls) achemine un numéro vers un trunk SIP, un renvoi ou une séquence.
- [Acheter et libérer un numéro](/docs/guides/numbers/buying-numbers) détaille l'achat via l'API.
- [Référence API Numbers](/docs/api/reference/list-workspace-numbers) documente chaque opération et chaque champ.

## 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)