API contacts, affaires et parcours

Ces endpoints permettent à votre propre code, à Zapier ou à n8n d'agir sur votre compte : ajouter des contacts, ouvrir et déplacer des affaires, inscrire des contacts dans des parcours, et lire les identifiants dont ces appels ont besoin. Ils utilisent la même clé API que l'API d'envoi.

Authorization: Bearer mia_live_...

Chaque famille d'endpoints accepte 60 requêtes par minute et par clé. Au-delà, vous recevez un 429. Les erreurs sont renvoyées sous la forme {"error": "…"} avec un statut 4xx. Le contrat complet, avec chaque forme de réponse, figure dans la spécification OpenAPI.

Contacts

Créer ou mettre à jour

POST /api/v1/contacts ajoute une adresse à une liste de contacts, ou la met à jour si elle y est déjà :

{
  "listId": "list_abc123",
  "email": "[email protected]",
  "fields": { "first_name": "Ada", "company": "Analytical Engines" }
}

La réponse est 201 pour un nouveau contact et 200 pour une mise à jour, avec le contact enregistré. Pour en envoyer jusqu'à 500 d'un coup, utilisez plutôt {"listId": "…", "contacts": [{"email": "…", "first_name": "…"}, …]}, qui répond avec des compteurs.

Chaque adresse est vérifiée à l'enregistrement. L'API n'enregistre jamais de réponse de consentement : ces contacts reçoivent vos envois comme avant. Un contact unique qui ferait dépasser la limite de contacts de votre forfait reçoit un 409.

Rechercher

GET /api/v1/[email protected] renvoie le contact de cette adresse dans chaque liste, du plus récent au plus ancien. Ajoutez &listId= pour ne chercher que dans une liste. Chaque recherche est consignée dans le journal d'accès aux données personnelles de votre compte, comme un contact consulté dans le tableau de bord.

Listes

GET /api/v1/lists renvoie l'id, le name, les fields et le rowCount de chaque liste de contacts. Aucune donnée de contact.

Affaires

Créer

POST /api/v1/deals :

{
  "email": "[email protected]",
  "title": "Annual plan",
  "value": 1200,
  "currency": "EUR"
}

Désignez le contact par email, ou par listId plus rowId. Avec seulement un e-mail, l'affaire va sur la liste mise à jour le plus récemment qui contient l'adresse. Sans pipelineId ni stageId, elle arrive dans la première étape en cours de votre pipeline par défaut. currency vaut USD par défaut.

Envoyez un en-tête Idempotency-Key (un numéro de commande, par exemple) pour sécuriser les nouvelles tentatives. Une répétition avec la même clé répond 200 avec "created": false au lieu de créer une deuxième affaire.

Mettre à jour ou déplacer

PATCH /api/v1/deals/{id} accepte title, value, currency et stageId. Déplacer vers une étape gagnée ou perdue clôt l'affaire. Le corps entier est vérifié d'abord : une étape inconnue ne change rien. Un déplacement déclenche le déclencheur de parcours Changement d'étape d'une affaire et le webhook deal.stage_changed, comme un déplacement sur le tableau.

Pipelines

GET /api/v1/pipelines renvoie vos pipelines, celui par défaut en premier, chacun avec ses étapes (id, name, kind). Utilisez-le pour trouver le stageId vers lequel déplacer une affaire.

Parcours

GET /api/v1/journeys liste vos parcours avec leur identifiant, leur nom, leur déclencheur et leur état (actif ou non). ?trigger=api ne renvoie que ceux dans lesquels votre code peut inscrire des contacts.

POST /api/v1/journeys/{id}/trigger avec {"email": "…", "listId": "…"} inscrit un contact dans un parcours dont le déclencheur est Appel d'API. Voir parcours.

Exemples d'événements

GET /api/v1/events/sample?type=deal.stage_changed renvoie {"events": [ … ]} avec un exemple d'enveloppe de webhook de ce type, ou un exemple de chaque type sans type. Les outils d'automatisation l'utilisent pour vous montrer les champs avant l'arrivée d'un vrai événement.

Webhooks

GET, POST /api/v1/webhooks et DELETE /api/v1/webhooks/{id} gèrent les abonnements aux événements. Voir webhooks et événements.