# Rechercher un numéro de téléphone

Un seul appel répond à ce qu'est un numéro. Tout ce qui suit nécessite une clé API avec le scope `lookup`.

## Lancer une recherche de base

Envoyez le numéro sans rien d'autre. La recherche de base est toujours facturée une fois, et elle renvoie toujours le pays, le réseau de desserte, le réseau d'attribution et un type de ligne approximatif.

**TypeScript**

```typescript
const answer = await bird.lookup.phoneNumber({
  phone_number: "+31612345678",
  type: ["classification", "score"],
});
console.log(answer.country_code, answer.line_type);
// Only a block whose status is ok carries a value, and only that one is billed.
if (answer.score?.status === "ok") console.log(answer.score.value);
```

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

## Comment écrire le numéro

Envoyez l'indicatif téléphonique du pays, puis le numéro national. Le `+` initial est facultatif et `00` fonctionne à sa place, donc `+31612345678`, `31612345678` et `0031612345678` désignent tous le même numéro.

Un numéro écrit pour un appel national, sans indicatif pays, est rejeté plutôt que deviné. `0612345678` renvoie [`E22000`](/docs/api/errors/E22000), car ajouter un indicatif pays désignerait un vrai numéro ailleurs et vous serait facturé.

## Ce que la recherche de base renvoie

`country_code` est le pays du numéro, absent lorsque le numéro n'appartient à aucun pays en particulier, comme c'est le cas pour une plage non géographique.

`network_info` est le réseau qui dessert le numéro aujourd'hui, et `original_network_info` est le réseau qui a attribué sa plage. Les deux diffèrent lorsque le numéro a été porté, et dans ce cas `flags` contient `ported`.

`line_type` indique le type de ligne du numéro : `mobile`, `fixed_line`, `voip`, `toll_free`, `premium_rate`, `satellite`, `pager`, `payphone`, `m2m`, `service`, `other` ou `unknown`. `unknown` signifie que la plateforme opérateur ne possède aucune classification pour la plage ; `other` signifie qu'elle en possède une sans équivalent ici. Pour le service alloué avec une précision plus fine, demandez la propriété `classification`. Elle interroge une source différente avec un vocabulaire plus large, et elle est rapportée séparément pour que vous puissiez toujours distinguer les deux.

## Ajouter des propriétés

Nommez les propriétés souhaitées dans `type`. Chacune est facturée séparément et uniquement lorsqu'elle est livrée.

| Propriété        | Ce qu'elle renvoie                                                                   |
| ---------------- | ------------------------------------------------------------------------------------ |
| `classification` | Le service alloué précis de la plage : surtaxé, satellite, M2M, cabine téléphonique. |
| `porting`        | Date du dernier changement de réseau et historique complet des portages.             |
| `presence`       | Si le numéro est actif sur le réseau.                                                |
| `roaming`        | S'il est en itinérance, et sur quel réseau.                                          |
| `sim_swap`       | Date du dernier changement de carte SIM.                                             |
| `score`          | Un score de crédibilité de 0 à 100.                                                  |

`classification`, `porting` et `score` lisent des données stockées et répondent rapidement. `presence`, `roaming` et `sim_swap` interrogent le réseau en temps réel, donc ils sont plus lents et leur couverture varie selon l'opérateur. Attendez-vous à recevoir `unavailable` ou `inconclusive` plus souvent pour ceux-ci que pour les propriétés stockées.

Deux propriétés répondent à des questions que la recherche de base aborde déjà, avec une résolution plus fine. `porting` vous donne la date et l'historique complet là où le flag `ported` de la recherche de base indique seulement si un portage a eu lieu. `classification` résout `line_type` vers le service alloué exact.

## Lire le statut avant la valeur

Chaque bloc de propriété porte un `status`, et seul `ok` contient une valeur.

```json
{
  "phone_number": "+441904123456",
  "country_code": "GB",
  "line_type": "service",
  "classification": {
    "status": "ok",
    "value": "premium_rate"
  },
  "score": {
    "status": "unavailable"
  }
}
```

Dans cette réponse, la recherche de base et `classification` vous ont été facturés. `score` ne vous a pas été facturé.

Lisez `status` en premier et traitez toute valeur autre que `ok` comme "not answered". C'est un vocabulaire ouvert : une valeur que vous ne reconnaissez pas est un statut futur, pas une erreur.

Deux blocs rapportent une borne plutôt qu'une valeur exacte lorsque le réseau ne la communique pas. `sim_swap` renvoie `min_days` et `max_days` au lieu de `last_swapped_at` lorsque seule une plage de récence est connue. `porting` définit `last_ported_at_is_approximate` lorsqu'un registre enregistre la période d'un portage mais pas son jour exact.

Un champ se lit comme un résultat négatif mais constitue un résultat positif : `porting.ported` défini à `false` signifie que le registre a été consulté et ne contient aucun portage pour ce numéro, et non que rien n'a pu être vérifié. C'est à cela que sert `status`.

## Réessayer sans payer deux fois

Une recherche est facturée, donc une requête réessayée ne doit pas acheter une deuxième réponse. Envoyez un `Idempotency-Key` et la répétition de la même requête rejoue la réponse stockée au lieu de lancer une nouvelle recherche. Voir [Idempotency](/docs/guides/idempotency).

La forme `GET` de cette opération, qui place le numéro dans l'URL, ne peut pas porter de clé d'idempotence. Utilisez la forme `POST` pour tout traitement automatisé.

## Erreurs

| Code                                | Ce qui s'est passé                                                                                          |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| [`E22000`](/docs/api/errors/E22000) | Le numéro n'est pas un numéro de téléphone valide au format international. Rien n'a été facturé.            |
| [`E22001`](/docs/api/errors/E22001) | Le solde de l'organisation ne couvre pas la recherche. Rechargez-le et réessayez. Rien n'a été facturé.     |
| [`E22002`](/docs/api/errors/E22002) | La recherche est temporairement indisponible. Réessayez avec un intervalle croissant. Rien n'a été facturé. |

Une propriété en échec n'est pas une erreur. Elle revient sous forme de statut sur son bloc, et la recherche de base est servie à côté.

## Étapes suivantes

- [Rechercher une adresse e-mail](/docs/guides/lookup/email-addresses) est l'autre volet de Lookup.
- [Référence API de Lookup](/docs/api/reference/create-phone-number-lookup) documente chaque champ et chaque bloc de propriété.
- [Limites de débit](/docs/guides/rate-limits) couvre le bucket `lookup` utilisé par ces appels.
- [Recherche de numéro de téléphone : vérifiez un numéro avant d'envoyer](/learn/lookup/phone-number-lookup-check-a-number-before-you-send) est une vidéo qui exécute une recherche et ajoute les vérifications réseau en temps réel.

## Related resources

- [Phone number lookup](/lookup-api) (product)

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