Présentation de l'API et authentification

L'API REST Ody se trouve à https://api.ody.co/v1/api et authentifie chaque requête avec une clé API envoyée comme un jeton Bearer — créez-en une dans Paramètres → API Développeur, puis appelez les points de terminaison ci-dessous.

Authentification

Envoyez votre clé dans l'en-tête Authorization pour chaque requête :

curl https://api.ody.co/v1/api/contacts \
  -H "Authorization: Bearer ody_live_…"

• Les clés existent en deux modes : les clés ody_live_… sont actives, les clés ody_test_… se comportent de manière identique mais les envois de messages sont simulés (enregistrés avec deliveryStatus: "simulated", jamais transmis). Voir Développer en toute sécurité avec le mode test.
• Une clé manquante, invalide ou révoquée renvoie 401 unauthenticated.
• Une clé restreinte par des scopes renvoie 403 permission_denied — nommant le scope manquant — lorsqu'elle appelle un point de terminaison en dehors de ses autorisations.
• Chaque appel s'exécute avec les permissions du membre qui a créé la clé, uniquement au sein de cet espace de travail.

Points de terminaison

Méthode et chemin	Ce qu'il fait	Scope requis
GET /v1/api/contacts	Lister ou rechercher des contacts (?q=, paginé)	contacts:read
POST /v1/api/contacts	Créer un contact	contacts:write
GET /v1/api/contacts/:id	Récupérer les détails complets d'un contact	contacts:read
PATCH /v1/api/contacts/:id	Mettre à jour un contact (seuls les champs fournis sont modifiés)	contacts:write
DELETE /v1/api/contacts/:id	Supprimer un contact	contacts:write
GET /v1/api/conversations	Lister les conversations (?status=open|done, paginé)	conversations:read
GET /v1/api/conversations/:id	Récupérer un fil de discussion complet	conversations:read
PATCH /v1/api/conversations/:id	Définir le statut — corps {"status":"open"} ou {"status":"done"}	conversations:write
POST /v1/api/messages	Envoyer un SMS/MMS (prend en charge Idempotency-Key)	messages:send
GET /v1/api/messages/search	Rechercher des corps de messages et des transcriptions (?q=)	conversations:read
GET /v1/api/calls	Lister l'historique des appels et des messages vocaux	conversations:read
POST /v1/api/calls	Passer un appel IA sortant — votre agent publié compose le numéro	calls:place
GET /v1/api/numbers	Lister les numéros de votre espace de travail	numbers:read
GET /v1/api/numbers/available	Rechercher des numéros que vous pouvez acheter (?country=, ?startsWith=, ?contains=, ?locality=, ?state=, ?limit=)	numbers:manage
POST /v1/api/numbers	Acheter un numéro — facturé comme un achat in-app (prend en charge Idempotency-Key)	numbers:manage
POST /v1/api/numbers/:e164/connect et …/disconnect	Acheminer un numéro vers ou depuis votre agent IA	agent:manage
GET /v1/api/messaging	Statut d'enregistrement 10DLC (step, canText)	numbers:manage
POST /v1/api/messaging/registration	Soumettre votre entreprise + campagne 10DLC (facturé)	numbers:manage
POST /v1/api/messaging/refresh	Revérifier et faire avancer l'examen de l'opérateur 10DLC	numbers:manage
GET/PATCH /v1/api/agent	Lire ou mettre à jour la configuration de votre agent IA (brouillon)	agent:manage
POST /v1/api/agent/publish	Mettre en ligne la configuration de votre agent	agent:manage
GET /v1/api/webhook-events	Lister les types d'événements de webhook auxquels on peut s'abonner	webhooks:manage
GET/POST /v1/api/webhooks et /v1/api/webhooks/:id…	Gérer les points de terminaison de webhook sortants	webhooks:manage
GET /v1/api/openapi.json	La spécification OpenAPI 3.1	none

Les points de terminaison de liste sont paginés avec ?limit= et ?cursor= — voir Pagination, idempotence et gestion des erreurs.

Contacts

POST /v1/api/contacts nécessite au moins un champ d'identité : firstName, lastName, company, un numéro de téléphone ou un e-mail. Les téléphones et les e-mails acceptent une chaîne simple ("phone": "+15125550123") ou des tableaux étiquetés complets ("phones": [{"value": "+15125550123", "label": "work"}]). Sur PATCH, seuls les champs que vous fournissez sont modifiés ; phones, emails, notes, properties et tags sont remplacés en bloc lorsqu'ils sont fournis.

Envoi d'un message

POST /v1/api/messages accepte soit un conversationId existant, soit un numéro de téléphone de destinataire dans to (format E.164). Avec to, Ody choisit le numéro d'envoi de votre espace de travail (ou respecte un from que vous possédez), crée la conversation si nécessaire et envoie le message. Ajoutez jusqu'à 10 mediaUrls publiquement accessibles pour les MMS :

curl https://api.ody.co/v1/api/messages \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-shipped" \
  -d '{"to":"+15125550123","body":"Your order shipped!"}'

Un espace de travail sans numéro de téléphone actif reçoit 409 failed_precondition. Les tentatives avec la même Idempotency-Key dans les 24 heures rejouent la première réponse au lieu d'envoyer le message en double.

Numéros, messagerie, appels IA et votre agent

L'API peut également gérer une ligne téléphonique de bout en bout : rechercher et acheter des numéros, enregistrer la messagerie 10DLC, configurer et publier votre agent IA, acheminer les numéros vers celui-ci et passer des appels IA sortants. Ces points de terminaison utilisent trois scopes qui leur sont propres — numbers:manage (Acheter des numéros et 10DLC), calls:place (Passer des appels IA), et agent:manage (Gérer l'agent IA) — et tout ce qu'ils font est enregistré sur votre compte exactement comme si vous l'aviez fait dans l'application, avec la même facturation et les mêmes règles. Voir Acheter des numéros et enregistrer la messagerie via l'API et Passer des appels IA et gérer Astra via l'API.

Erreurs, ID de requête et limites de débit

Chaque erreur utilise une enveloppe uniforme, et chaque réponse (succès ou erreur) contient un en-tête X-Request-Id — citez-le lorsque vous contactez le support :

{ "error": { "code": "not_found", "message": "Contact not found", "requestId": "req_…" } }

Chaque clé reçoit 600 requêtes/minute avec les en-têtes RateLimit-* standard. Détails dans Limites de débit de l'API et bonnes pratiques et Pagination, idempotence et gestion des erreurs.

Articles connexes

• Obtenir votre clé API Ody
• Recevoir des webhooks et vérifier les signatures
• Pagination, idempotence et gestion des erreurs
• Démarrage rapide SDK : TypeScript et Python