Référence de l’API

Parcourir par ressource

Votre clé

Appels

Fiches

Messages texte

RequêteGET

GET /api/v1/calls

curl "https://api.inboundcx.com/api/v1/calls?direction=inbound&limit=1" \
  -H "Authorization: Bearer $API_KEY"

Réponse200 OK

{
  "calls": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "direction": "inbound",
      "fromNumber": "+15145550142",
      "toNumber": "+14385550199",
      "status": "completed",
      "startedAt": "2026-09-11T15:04:12.000Z",
      "answeredAt": "2026-09-11T15:04:19.000Z",
      "endedAt": "2026-09-11T15:07:31.000Z",
      "durationSec": 192,
      "isInternal": false,
      "agentId": "a3f1c2d4-5b6e-4f70-8a9b-0c1d2e3f4a5b",
      "contactId": "e2b4c6d8-1a3f-4b5d-9e7c-8f0a2b4c6d8e"
    }
  ],
  "nextCursor": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

Clés et portées

Chaque requête porte une clé d’API en jeton de porteur. Les clés se créent dans le portail, sous Settings, API Keys, sur les forfaits Pro et Business. La clé complète n’apparaît qu’une fois et n’est conservée que sous forme d’empreinte : une clé perdue se remplace, elle ne se récupère pas.

Authorization: Bearer rk_live_…

Une clé appartient à une seule organisation, et l’organisation se déduit de la clé elle-même. Il n’y a aucun identifiant de compte à transmettre. Si l’organisation passe à un forfait sans accès à l’API, ses clés sont refusées avec un code 403 jusqu’à son retour.

https://api.inboundcx.com/api/v1

Ouvrir API Keys dans le portail

Portées

Ce qui est appliqué à chaque requête est l’intersection des portées de la clé et de ces cinq-là : une clé ne peut donc jamais détenir ce qui n’y figure pas. Une clé créée dans le portail détient les cinq. Interrogez GET /api/v1/me pour connaître les portées réellement détenues, ce qui permet de distinguer un refus d’une fonction absente.

Portée	Accès	Ce qu’elle permet
calls.view.team	Lecture	Lire l’historique des appels.
contacts.view	Lecture	Lire le répertoire.
contacts.manage	Écriture	Créer, modifier et supprimer des fiches.
sms.view	Lecture	Lire les conversations texte.
sms.send	Écriture	Envoyer des messages texte, ce qui est facturé à l’organisation.

La description lisible par machine est un document OpenAPI 3.1, produit à partir des mêmes schémas que ceux validés par le code, et servi sans clé.

Ouvrir le document OpenAPI

Trois événements, tous signés

Chaque livraison est un POST HTTPS signé en HMAC-SHA256 sur l’horodatage et le corps brut. Une livraison ratée est relancée avec un délai exponentiel : 8 tentatives en tout, sur un peu plus de deux heures.

call.completedUn appel s’est terminé : sens, numéros, statut, personne qui a répondu, durée et heures.
voicemail.receivedUn appelant a laissé un message et l’enregistrement est prêt. La transcription l’accompagne si elle est déjà arrivée.
sms.receivedUn message texte est arrivé sur l’un des numéros de l’organisation, avec son contenu.
8 tentativesRelancé avec un délai exponentiel à partir de 1 minute, plafonné à 60, sur un peu plus de deux heures.
Au moins une foisChaque relance porte la même valeur X-InboundCX-Delivery. Servez-vous-en pour ignorer un doublon.
Historique des livraisonsChaque point de terminaison du portail affiche ses livraisons récentes : statut, tentatives, prochaine relance et dernière erreur.

Les en-têtes

En-tête	Ce qu’il transporte
X-InboundCX-Event X-Ringfully-Event Obsolète	Le nom de l’événement, par exemple call.completed.
X-InboundCX-Timestamp X-Ringfully-Timestamp Obsolète	Millisecondes depuis l’époque Unix. Utilisez la valeur telle quelle, comme une chaîne opaque, sans la reformater.
X-InboundCX-Signature X-Ringfully-Signature Obsolète	HMAC-SHA256 en hexadécimal minuscule sur la charge signée ci-dessous.
X-InboundCX-Delivery X-Ringfully-Delivery Obsolète	Identique à chaque nouvelle tentative d’une même livraison. Servez-vous-en comme clé d’idempotence : la livraison est au moins une fois, jamais exactement une fois.

Chaque livraison porte aussi les quatre mêmes en-têtes sous leurs noms obsolètes, de X-Ringfully-Event à X-Ringfully-Delivery, avec des valeurs identiques. Ces noms seront retirés 12 mois après le changement de nom : lisez plutôt les noms X-InboundCX. Rien d’autre ne change, puisque la signature ne couvre aucun nom d’en-tête.

Une tentative qui ne répond pas par un code 2xx en 10 secondes compte comme un échec, et une redirection n’est pas suivie. La livraison passe par une file : un événement peut arriver jusqu’à une minute après s’être produit. L’adresse doit être en https, sur un hôte que votre organisation a approuvé.

Vérifier une livraison

Lisez X-InboundCX-Timestamp comme une chaîne, exactement telle qu’elle est envoyée.
Prenez le corps brut de la requête, avant toute analyse JSON. Analyser puis resérialiser ne redonne pas les mêmes octets et ne correspondra pas.
Assemblez-les : signedPayload = timestamp + « . » + corps brut.
Calculez le HMAC-SHA256 de cette chaîne avec le secret de votre point de terminaison, en hexadécimal minuscule.
Comparez le résultat à X-InboundCX-Signature avec une comparaison à temps constant.
Rejetez un horodatage à plus de cinq minutes de votre propre horloge. L’étape cinq prouve que le message vient de nous; seule celle-ci prouve qu’il vient d’arriver.

import crypto from "node:crypto";

// Deprecated names with the same values: x-ringfully-timestamp, x-ringfully-signature.
const timestamp = req.get("x-inboundcx-timestamp") ?? "";
const signature = req.get("x-inboundcx-signature") ?? "";
const expected = crypto
  .createHmac("sha256", process.env.INBOUNDCX_WEBHOOK_SECRET)
  .update(`${timestamp}.${rawBody}`)
  .digest("hex");
const valid =
  expected.length === signature.length &&
  crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature)) &&
  Math.abs(Date.now() - Number(timestamp)) < 5 * 60 * 1000;

L’exemple lit le secret dans INBOUNDCX_WEBHOOK_SECRET. Une intégration qui le garde dans RINGFULLY_WEBHOOK_SECRET détient la même valeur : renommer la variable est facultatif.

Limites et versions

Limites de débit

120 requêtes par minute par clé, et 600 par minute par réseau avant même la vérification de la clé. La limite suit la clé plutôt que l’organisation : un traitement par lots peut avoir sa propre clé sans ralentir l’intégration en service.

Les réponses portent RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset. Une requête refusée reçoit un code 429 avec Retry-After.

Versions

La version 1, à /api/v1, est la seule, servie depuis août 2026. Aucun en-tête de version n’est à transmettre.

Dans la version 1, des champs peuvent s’ajouter, mais aucun n’est retiré ni renommé. De nouveaux paramètres facultatifs, de nouveaux champs de réponse et de nouveaux points de terminaison peuvent apparaître à tout moment : ignorez les champs que vous ne reconnaissez pas. Tout ce qui retirerait ou renommerait un champ paraîtra en version 2, à une autre adresse.