Acheter des numéros et enregistrer la messagerie via l'API

L'API peut rechercher des numéros de téléphone disponibles à l'achat, les acheter et enregistrer votre entreprise pour la messagerie 10DLC — avec la même facturation, les mêmes exigences et les mêmes résultats que si vous le faisiez dans l'application. Un numéro acheté via POST /v1/api/numbers apparaît immédiatement dans Paramètres → Numéros, et un enregistrement déposé via l'API s'affiche dans la carte Configuration de la messagerie texte, vous permettant d'intervenir et de gérer l'un ou l'autre depuis l'application à tout moment.

Avant de commencer

• Votre clé API nécessite la portée numbers:manage — la puce Acheter des numéros et 10DLC dans Paramètres → API Développeur. Les clés d'accès complet l'incluent automatiquement. Voir Obtenir votre clé API Ody.
• Les mêmes règles que pour l'application s'appliquent : votre espace de travail doit avoir un forfait actif pour acheter, et si Ody vous a demandé de vérifier votre identité, cela doit être fait au préalable — l'API renvoie 409 failed_precondition tant que ce n'est pas le cas.
• La facturation est identique à celle de l'application : votre forfait inclut un numéro, et chaque numéro supplémentaire est facturé comme l'option de numéro additionnel à 5 $/mois. Voir Ajouter des numéros supplémentaires.

Rechercher des numéros disponibles

GET /v1/api/numbers/available recherche les numéros que vous pouvez acheter. Filtrez avec country (US par défaut), startsWith (par exemple, un indicatif régional), contains, locality, state et limit (20 par défaut, 50 max) :

curl "https://api.ody.co/v1/api/numbers/available?startsWith=512&limit=5" \
  -H "Authorization: Bearer ody_live_…"

Chaque candidat inclut son numéro et le prix mensuel que vous paieriez réellement à Ody :

{
  "available": [
    {
      "phone_number": "+15125550123",
      "cost_information": { "monthly_cost": "5.00", "upfront_cost": "0.00", "currency": "USD" }
    }
  ]
}

Acheter un numéro

POST /v1/api/numbers commande un numéro à partir des résultats de recherche. Envoyez un en-tête Idempotency-Key afin qu'une nouvelle tentative de réseau ne puisse jamais acheter le numéro deux fois — une nouvelle tentative dans les 24 heures rejoue la réponse originale avec un en-tête Idempotency-Replayed: true :

curl https://api.ody.co/v1/api/numbers \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: onboarding-main-line" \
  -d '{"phoneNumber":"+15125550123"}'

Le numéro est commandé, ajouté à votre espace de travail et facturé sur votre abonnement existant — exactement comme si vous cliquiez sur Acheter dans l'application. Il apparaît immédiatement dans Paramètres → Numéros, où vous (ou votre équipe) pouvez configurer l'ordre de sonnerie, la messagerie vocale, un menu téléphonique ou l'agent AI, comme n'importe quel autre numéro. Les appels fonctionnent immédiatement ; l'envoi de SMS depuis un numéro local est bloqué jusqu'à ce que l'enregistrement 10DLC soit approuvé (ci-dessous).

S'inscrire à la messagerie (10DLC)

Les opérateurs américains exigent l'enregistrement des entreprises avant qu'un numéro local ne puisse envoyer des SMS — l'API reflète le flux de Configuration de la messagerie texte dans l'application S'inscrire à la messagerie 10DLC.

Vérifiez le statut avec GET /v1/api/messaging. L'step de la réponse parcourt l'examen de l'entreprise (marque) puis l'examen de la campagne, et canText passe à true dès que les opérateurs approuvent — la messagerie fonctionne alors partout, application et API confondues.

Soumettez votre enregistrement avec POST /v1/api/messaging/registration. Le bloc business nécessite displayName, email, vertical, street, city, state et postalCode — plus votre companyName légal et votre EIN, à moins que vous ne vous enregistriez en tant qu'entreprise individuelle (entityType: "SOLE_PROPRIETOR" avec firstName, lastName et un numéro de téléphone de contact à la place). Le bloc campaign est facultatif ; des valeurs par défaut sensées (un cas d'utilisation mixte avec une gestion conforme de STOP/HELP) sont appliquées :

curl https://api.ody.co/v1/api/messaging/registration \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "business": {
      "displayName": "Acme Plumbing",
      "email": "[email protected]",
      "vertical": "PROFESSIONAL",
      "companyName": "Acme Plumbing LLC",
      "ein": "12-3456789",
      "street": "600 Congress Ave",
      "city": "Austin",
      "state": "TX",
      "postalCode": "78701"
    },
    "campaign": {
      "description": "Customer care and appointment notifications",
      "samples": ["Acme Plumbing: your appointment is confirmed for Tuesday at 9am."]
    }
  }'

Un dépôt via l'API est facturé exactement comme un dépôt dans l'application, y compris les frais d'enregistrement uniques de 20 $. Utilisez POST /v1/api/messaging/refresh pour revérifier l'examen de l'opérateur et faire avancer le pipeline ; l'approbation progresse également automatiquement.

Depuis un assistant AI (MCP)

Les mêmes capacités sont disponibles en tant qu'outils MCP, de sorte qu'un assistant connecté peut exécuter tout ce flux pour vous : search_numbers, buy_number, get_messaging_status et submit_10dlc_registration. Voir Connecter les outils AI avec MCP.

Mode test

Avec une clé ody_test_…, POST /numbers renvoie un achat simulé ("simulated": true) — rien n'est commandé, provisionné ou facturé — et les enregistrements 10DLC sont déposés en mode simulé : le pipeline complet s'exécute sans soumission au registre et sans frais. Voir Développer en toute sécurité avec le mode test.

Articles connexes

• Acheter un numéro de téléphone
• S'inscrire à la messagerie 10DLC
• Passer des appels AI et gérer Astra via l'API
• Développer en toute sécurité avec le mode test

---