Gérer ses numéros : chercher, commander, lister

Avant de commencer

Une clé de test fictive : tq_test_EXEMPLE.
Un projet auquel rattacher le numéro. Ici : prj_EXEMPLE_A.
Le pays et le type de numéro recherchés (par exemple local en France).

Version de démonstration. Conception susceptible d’évoluer. Aucune API de production n’est ouverte, aucun numéro réel n’est commandé.

Chercher un numéro

GET /numbers/search accepte au minimum country et type. Chaque résultat indique ses capacités (voix, SMS) et le champ documents_required : la liste des justificatifs à fournir avant l’activation. Lisez-la avant de commander.

Exemple fictif : recherche dans un stock de démonstration. Les numéros appartiennent à une plage fictive.

curl "https://api.example.test/v1/numbers/search?country=FR&type=local" \
  -H "Authorization: Bearer tq_test_EXEMPLE"

Exemple de réponse à la recherche

Exemple fictif de réponse. La valeur de documents_required est illustrative.

{
  "data": [
    {
      "e164": "+33199001234",
      "country": "FR",
      "type": "local",
      "capabilities": ["voice", "sms"],
      "documents_required": ["proof_of_address"]
    }
  ]
}

Commander le numéro

Choisissez un résultat de la recherche et notez son e164.
Envoyez POST /number-orders avec e164 et project_id, accompagné d’une Idempotency-Key.
Lisez le statut de la réponse : pending_validation signifie que la commande attend la validation des justificatifs et des conditions. Le numéro n’est pas encore utilisable.
Attendez l’événement number.activated (webhook) ou relisez la liste de vos numéros.

Exemple fictif : la commande est une simulation tant qu’aucun fournisseur n’est configuré. Aucun numéro réel n’est réservé.

curl -X POST https://api.example.test/v1/number-orders \
  -H "Authorization: Bearer tq_test_EXEMPLE" \
  -H "Idempotency-Key: c2a97e51-6f08-4b3d-8e14-9d5a0b7c3f28" \
  -H "Content-Type: application/json" \
  -d '{"e164":"+33199001234","project_id":"prj_EXEMPLE_A"}'

Lister votre parc

GET /numbers renvoie vos numéros avec leur projet et leur statut. La pagination est par curseur : passez limit, puis le next_cursor reçu comme paramètre cursor pour obtenir la page suivante. Quand next_cursor est nul, vous avez tout lu.

Exemple fictif : lecture du parc de démonstration.

curl "https://api.example.test/v1/numbers?limit=20" \
  -H "Authorization: Bearer tq_test_EXEMPLE"

Erreurs fréquentes

Symptôme	Cause probable	Que faire
Aucun résultat	Pays ou type sans stock, ou capacité non validée pour ce pays.	Changez de type, ou demandez un devis pour votre pays.
404 not_found	Projet ou numéro inexistant, ou hors de votre périmètre.	Vérifiez l’identifiant.
409 idempotency_conflict	Même clé, corps différent.	Nouvelle clé pour une nouvelle commande.
Commande bloquée en pending_validation	Justificatifs manquants ou en cours d’examen.	Fournissez les pièces listées dans documents_required.

Ce que ce guide ne fait pas

Il ne commande aucun numéro réel et ne garantit ni stock ni délai : les délais se confirment avec le fournisseur retenu.
Il ne traite pas la résiliation d’un numéro ni la portabilité d’un numéro existant. Pour ce dernier cas, voir « Préparer une portabilité ».
Un numéro disponible suppose un pays et une capacité approuvés, du stock, un compte autorisé et des obligations satisfaites. L’un des quatre manquant, la commande n’aboutit pas.

Passer un premier appel avec l’un de vos numéros Numéros virtuels

Gérer ses numéros par API