Référence API

L'API REST Manivox.ai vous permet de lire les données d'agents et d'appels par programme. Tous les endpoints retournent du JSON et requièrent une clé API.

URL de base

https://www.manivox.ai/api/v1

Endpoints

L'API publique /v1 lit vos données et passe des appels sortants. Chaque endpoint s'authentifie avec une clé API (Bearer la_…), et ce qu'une clé peut faire dépend des permissions choisies à sa création — une clé est en lecture seule tant que vous ne lui accordez pas une permission d'appel.

L'automatisation des campagnes sortantes — création, ajout de contacts, démarrage et pause, lecture de l'avancement, gestion des exclusions — est disponible sur /v1 avec une clé API et la permission campaigns:write. Voir la page API Campagnes. Les mêmes opérations existent aussi sous /api avec l'authentification de session ; c'est ce que le dashboard lui-même utilise, et c'est la plus ancienne des deux.

Authentification

Chaque requête doit inclure votre clé API comme Bearer token dans l'en-tête Authorization :

curl https://www.manivox.ai/api/v1/ping \
  -H "Authorization: Bearer la_YOUR_API_KEY"

Les clés API commencent par le préfixe la_. Une clé au format invalide, ou qui n'existe pas (supprimée ou faute de frappe), retourne 401 ; une clé révoquée ou désactivée (inactive) retourne 403 avec API key is inactive.

Activer l'accès à l'API

L'accès à l'API s'active par organisation. Demandez à votre interlocuteur Manivox d'activer l'accès API pour votre organisation. Lorsque l'accès est activé et que l'organisation n'a encore aucune clé active, une première clé est générée automatiquement et affichée une seule fois : copiez-la immédiatement. Tant que l'accès n'est pas activé, chaque requête /v1 retourne 403.

Gérer vos clés API

Une fois l'accès activé, les admins de l'organisation gèrent eux-mêmes les clés depuis le dashboard :

1. Connectez-vous au dashboard Manivox.ai avec un compte admin de l'organisation (la gestion des clés est réservée aux admins)
2. Allez dans Paramètres → API
3. Générez une nouvelle clé et donnez-lui un nom descriptif (ex : production-server)
4. Copiez la valeur complète la_… depuis le bandeau de copie immédiatement : elle n'est affichée qu'une fois et n'est jamais stockée en clair

Cycle de vie d'une clé

Depuis Paramètres → API, vous pouvez révoquer une clé (elle devient inactive et retourne immédiatement 403) ou la supprimer entièrement. Il n'y a pas de bouton de rotation : pour faire tourner une clé, générez-en une nouvelle et supprimez l'ancienne. Une organisation peut détenir plusieurs clés à la fois.

Permissions (scopes)

Chaque clé API porte un ensemble de permissions, choisies à sa création dans Paramètres → Clés API. Une requête vers un endpoint pour lequel votre clé n'est pas habilitée renvoie 403 en nommant la permission manquante.

Les nouvelles clés sont en lecture seule par défaut, et toute clé créée avant l'existence des permissions est en lecture seule — accorder à une clé le droit de consommer votre solde est toujours un acte délibéré. calls:write et campaigns:write sont séparées volontairement : une clé confiée à un formulaire pour demander un rappel ne doit pas pouvoir lancer mille appels.

Réessayer sans risque

Les requêtes d'écriture acceptent un en-tête Idempotency-Key : n'importe quelle chaîne que vous générez par action, par exemple un identifiant de commande ou de ticket.

curl -X POST https://www.manivox.ai/api/v1/calls \
  -H "Authorization: Bearer la_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: commande-4821-rappel" \
  -d '{"agent_id": "...", "to_number": "+33612345678"}'

Un nouvel essai portant la même clé renvoie la première réponse au lieu d'agir de nouveau, avec un en-tête Idempotent-Replay: true. C'est ce qui rend inoffensifs un double-clic, un timeout réseau ou un webhook renvoyé : sans cela, chacun de ces cas passe un second appel réel. Les clés sont mémorisées 24 heures et sont propres à votre organisation.

Deux cas à connaître : réutiliser une clé pour un corps de requête différent renvoie 422 (c'est un bug côté appelant, et renvoyer le résultat antérieur le masquerait), et une requête en échec ne consomme pas sa clé — vous pouvez réessayer la requête corrigée avec la même.

Déclencher depuis une page sans backend

La règle ci-dessus — ne jamais mettre une clé dans du JavaScript navigateur — suppose que vous avez un serveur pour la garder. Quand ce n'est pas le cas (site statique, formulaire no-code, widget embarqué), un jeton d'action est la façon sûre de laisser la page déclencher elle-même un appel.

Votre serveur crée un jeton pour une action, tous paramètres figés :

curl -X POST https://www.manivox.ai/api/v1/action-tokens \
  -H "Authorization: Bearer la_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "calls.create",
    "params": { "agent_id": "...", "to_number": "+33612345678" },
    "ttl_seconds": 300,
    "origin": "https://app.example.com"
  }'

La page le consomme ensuite, sans clé et sans corps de requête :

await fetch(spendUrl, { method: 'POST' });
// → { "id": "clx7...", "status": "RINGING" }

La création exige la même permission que l'appel direct — calls.create demande calls:write — car c'est la moitié privilégiée. La consommation ne porte aucun justificatif, et c'est tout l'intérêt.

Ce qui rend un jeton exposable

• Le navigateur ne peut pas changer ce qu'il fait. Les paramètres sont figés à la création, et tout ce que la page envoie dans le corps est ignoré. C'est la propriété sur laquelle repose tout le reste : si la page pouvait choisir le numéro, vous auriez publié un automate d'appel.
• Il fonctionne une fois. Le jeton est réservé avant l'exécution, donc deux requêtes simultanées ne peuvent pas composer deux fois. Une seconde consommation renvoie le premier résultat avec Idempotent-Replay: true plutôt qu'un refus — une requête navigateur qui meurt après être arrivée est un cas ordinaire, et « déjà utilisé » laisserait votre visiteur dans le doute.
• Il expire. Cinq minutes par défaut, quinze au maximum. Un jeton consommé cesse aussi de rejouer passée son expiration.
• Il peut être lié à votre origine. Renseignez origin et le jeton ne fonctionne que depuis ce site ; la réponse porte le CORS de cette seule origine, jamais un joker.
• Il ne lit rien. La réponse est l'identifiant de l'appel et son statut. Un jeton n'est jamais un moyen de lire vos données.
• Il est tracé. Quelle clé l'a créé, quand il a été consommé, depuis quelle origine et quelle IP.

Au pire, un jeton volé permet donc cet appel-là, vers ce numéro, une fois, dans les minutes qui suivent — ce que le visiteur allait faire de toute façon. À comparer à une clé API fuitée, qui appelle n'importe qui, autant de fois qu'on veut, jusqu'à révocation.

Ce qu'il ne fait pas

Une conséquence de la réservation du jeton avant l'exécution : un jeton est consommé même quand l'action échoue. Si le solde était épuisé ou l'agent supprimé, le visiteur voit l'erreur et votre serveur doit créer un nouveau jeton pour réessayer. C'est le compromis assumé : autoriser un nouvel essai avec le même jeton supposerait de trancher quelles erreurs sont transitoires, et se tromper là-dessus appelle quelqu'un deux fois.

Si vous avez déjà un serveur dans le circuit, rien de tout cela n'est nécessaire — gardez-y la clé et appelez POST /v1/calls. Les jetons d'action existent pour le cas où ce serveur n'existe pas.

Pagination

Les endpoints de liste utilisent une pagination basée sur l'offset avec les paramètres de requête limit et offset. La limit maximale est de 100.

# Récupérer les appels 51-100
GET /v1/accounts/{id}/calls?limit=50&offset=50

La réponse inclut toujours un champ total avec le nombre total d'enregistrements correspondants.

Format d'erreur

Les erreurs retournent un objet JSON avec un champ error décrivant ce qui a mal tourné. La seule exception est un rejet par le limiteur de requêtes de la plateforme, qui retourne le corps standard du framework { "message": "Too Many Attempts." } : considérez le statut HTTP comme la référence et le corps comme une simple indication.

// 401, clé API absente ou invalide
{ "error": "Invalid API key" }

// 404, ressource introuvable
{ "error": "Account not found" }

// 422, paramètre de requête invalide
{ "error": "Invalid \"from\" datetime format. Use ISO 8601 (e.g. 2026-01-15T10:00:00)" }

// 403, la clé n'a pas la permission requise par cet endpoint
{
  "error": "This API key does not have the required scope",
  "required_scope": "calls:write",
  "key_scopes": ["read"]
}

// 409, une écriture avec la même Idempotency-Key est encore en cours
{ "error": "A request with this Idempotency-Key is still in progress" }

// 429, limite d'appels concurrents
{
  "error": "Concurrent call limit reached",
  "active_calls": 10,
  "max_concurrent_calls": 10
}

Codes de statut HTTP

Limites de débit

Trois compteurs s'appliquent, et dépasser l'un d'eux retourne 429 Too Many Requests : appliquez un backoff puis réessayez.

• Lectures (chaque GET sous /v1) : 120 requêtes par minute. Ce compteur est indexé sur l'adresse IP cliente qui atteint la plateforme, donc tout le trafic derrière une même adresse de sortie le partage, quelle que soit la clé ou l'organisation dont il provient.
• Écritures (POST /v1/calls, POST /v1/action-tokens et chaque écriture de campagne) : 20 requêtes par minute et par clé API. Volontairement bas : ces endpoints composent de vrais numéros et dépensent votre solde ; mettez votre travail en file plutôt que de l'envoyer en rafale.
• Dépenser un jeton d'action (POST /v1/actions/{token}, sans clé) : 30 requêtes par minute et par IP cliente.

Journalisation des requêtes

Chaque requête /v1 est journalisée, y compris les appels réussis et les rejets 401 / 403 / 429. Chaque entrée enregistre l'horodatage, la méthode HTTP, le chemin, le statut de réponse, l'IP cliente, le user agent et la durée en millisecondes. Les journaux sont purgés automatiquement au bout d'environ 90 jours.

Vous pouvez consulter cette activité dans le dashboard sous Paramètres → API → Activité API récente (les requêtes les plus récentes, avec l'heure, la requête, le statut et l'IP). Les opérateurs Manivox.ai voient la même activité récente dans la carte API Access de l'organisation. Un type de requête manque dans cette vue : dépenser un jeton d'action (POST /v1/actions/{token}) ne porte aucune clé API, il est donc journalisé sans organisation et n'apparaît pas dans votre Activité API récente ; les champs d'audit du jeton lui-même (quelle clé l'a émis, quand et d'où il a été dépensé) sont la trace à privilégier.

Comptes et connexions

Un compte est l'un des clients finaux de votre organisation (l'entité pour laquelle un agent agit). Une connexion est un toolkit tiers (CRM, agenda, etc.) lié à un compte pour que les agents puissent appeler ses outils. Les quatre endpoints ci-dessous sont en lecture seule et s'authentifient avec une clé API.

Lister les comptes

Retourne les comptes de l'organisation, triés par nom.

GET /v1/accounts

Auth : clé API (Bearer la_…)

curl "https://www.manivox.ai/api/v1/accounts?limit=50" \
  -H "Authorization: Bearer la_YOUR_API_KEY"

Réponse, 200 OK

{
  "data": [
    {
      "id": "acc_01hx...",
      "name": "Acme Corp",
      "city": "Paris",
      "country": "FR",
      "created_at": "2026-05-26T14:30:00+00:00"
    }
  ],
  "total": 12
}

Détail d'un compte

Retourne un seul compte avec son adresse complète, son représentant et son statut KYC.

GET /v1/accounts/{id}

Auth : clé API (Bearer la_…)

Réponse, 200 OK

{
  "id": "acc_01hx...",
  "name": "Acme Corp",
  "country": "FR",
  "address": {
    "street_number": "10",
    "street": "Rue de la Paix",
    "postal_code": "75002",
    "city": "Paris"
  },
  "representative": {
    "first_name": "Marie",
    "last_name": "Dupont",
    "role": "CEO",
    "email": "marie@acme.example",
    "phone": "+33612345678"
  },
  "kyc_status": "VALIDATED",
  "created_at": "2026-05-26T14:30:00+00:00"
}

Erreur, 404 Not Found : le compte n'existe pas pour l'organisation de cette clé API :

{ "error": "Account not found" }

Lister les connexions

Retourne les connexions tierces liées à un compte, les plus récentes d'abord.

GET /v1/accounts/{id}/connections

Auth : clé API (Bearer la_…)

# Uniquement les connexions actives
curl "https://www.manivox.ai/api/v1/accounts/acc_01hx.../connections?status=active" \
  -H "Authorization: Bearer la_YOUR_API_KEY"

Réponse, 200 OK

{
  "data": [
    {
      "id": "con_01hx...",
      "reference": "acme-hubspot",
      "toolkit_slug": "hubspot",
      "toolkit_name": "HubSpot",
      "status": "ACTIVE",
      "created_at": "2026-05-26T14:30:00+00:00",
      "updated_at": "2026-05-26T14:35:00+00:00"
    }
  ],
  "total": 3
}

Détail d'une connexion

Retourne une seule connexion par son id. L'objet a la même forme qu'une entrée de la liste ci-dessus.

GET /v1/accounts/{id}/connections/{connectionId}

Auth : clé API (Bearer la_…)

{
  "id": "con_01hx...",
  "reference": "acme-hubspot",
  "toolkit_slug": "hubspot",
  "toolkit_name": "HubSpot",
  "status": "ACTIVE",
  "created_at": "2026-05-26T14:30:00+00:00",
  "updated_at": "2026-05-26T14:35:00+00:00"
}

Erreurs, 404 Not Found

// Le compte n'existe pas pour l'organisation de cette clé API
{ "error": "Account not found" }

// Le compte existe mais l'id de connexion est inconnu
{ "error": "Connection not found" }

Explorateur d'API interactif

Le dashboard intègre une référence API sous Paramètres → API → Documentation API : chaque endpoint /v1 est présenté sous forme de carte dépliable avec ses paramètres, un exemple curl prêt à copier et un exemple de réponse. Chaque carte dispose aussi d'un testeur Essayer en direct — collez votre clé API (et un identifiant d'appel lorsque l'endpoint en a besoin) et lancez une vraie requête sans quitter le navigateur. L'URL de base et le format de l'en-tête Authorization sont affichés en haut.

Health check

Utilisez l'endpoint ping pour vérifier votre clé API et la connectivité :

curl https://www.manivox.ai/api/v1/ping \
  -H "Authorization: Bearer la_YOUR_API_KEY"

# 200 OK
{ "status": "ok", "organization_id": "org_01hx...", "timestamp": "2026-06-29T10:00:00+00:00" }