API für Kontakte, Deals & Journeys

Mit diesen Endpunkten können Ihr eigener Code, Zapier oder n8n in Ihrem Konto handeln: Kontakte hinzufügen, Deals anlegen und verschieben, Kontakte in Journeys aufnehmen und die IDs lesen, die diese Aufrufe brauchen. Sie nutzen denselben API-Schlüssel wie die Send API.

Authorization: Bearer mia_live_...

Jede Gruppe von Endpunkten erlaubt 60 Anfragen pro Minute und Schlüssel. Darüber erhalten Sie 429. Fehler kommen als {"error": "…"} mit einem 4xx-Status zurück. Der vollständige Vertrag mit jeder Antwortform steht in der OpenAPI-Spezifikation.

Kontakte

Anlegen oder aktualisieren

POST /api/v1/contacts fügt eine Adresse einer Kontaktliste hinzu oder aktualisiert sie, wenn sie schon vorhanden ist:

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

Die Antwort ist 201 für einen neuen Kontakt und 200 für eine Aktualisierung, jeweils mit dem gespeicherten Kontakt. Um bis zu 500 auf einmal zu senden, verwenden Sie stattdessen {"listId": "…", "contacts": [{"email": "…", "first_name": "…"}, …]}; die Antwort enthält dann Zähler.

Jede Adresse wird beim Speichern geprüft. Die API erfasst nie eine Einwilligungsantwort, diese Kontakte erhalten also Versände wie bisher. Ein einzelner Kontakt, der die Kontaktgrenze Ihres Tarifs überschreiten würde, erhält 409.

Suchen

GET /api/v1/[email protected] liefert den Kontakt dieser Adresse in jeder Liste, den neuesten zuerst. Mit &listId= suchen Sie nur in einer Liste. Jede Suche wird im Zugriffsprotokoll für personenbezogene Daten Ihres Kontos festgehalten, wie ein im Dashboard angesehener Kontakt.

Listen

GET /api/v1/lists liefert id, name, fields und rowCount jeder Kontaktliste. Keine Kontaktdaten.

Deals

Anlegen

POST /api/v1/deals:

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

Benennen Sie den Kontakt mit email oder mit listId plus rowId. Mit nur einer E-Mail-Adresse landet der Deal auf der zuletzt aktualisierten Liste, die die Adresse enthält. Ohne pipelineId und stageId kommt er in die erste offene Phase Ihrer Standard-Pipeline. currency ist standardmäßig USD.

Senden Sie einen Header Idempotency-Key (etwa eine Bestellnummer), damit Wiederholungen sicher sind. Eine Wiederholung mit demselben Schlüssel antwortet 200 mit "created": false, statt einen zweiten Deal anzulegen.

Aktualisieren oder verschieben

PATCH /api/v1/deals/{id} nimmt title, value, currency und stageId an. Eine Verschiebung in eine gewonnene oder verlorene Phase schließt den Deal. Der ganze Body wird zuerst geprüft, eine unbekannte Phase ändert also nichts. Eine Verschiebung löst den Journey-Auslöser Deal-Phase geändert und den Webhook deal.stage_changed aus, genau wie eine Verschiebung auf dem Board.

Pipelines

GET /api/v1/pipelines liefert Ihre Pipelines, die Standard-Pipeline zuerst, jeweils mit ihren Phasen (id, name, kind). So finden Sie die stageId, in die ein Deal verschoben werden soll.

Journeys

GET /api/v1/journeys listet Ihre Journeys mit ID, Name, Auslöser und ob sie aktiv sind. ?trigger=api liefert nur die, in die Ihr Code Kontakte aufnehmen kann.

POST /api/v1/journeys/{id}/trigger mit {"email": "…", "listId": "…"} nimmt einen Kontakt in eine Journey mit dem Auslöser API-Aufruf auf. Siehe Journeys.

Beispielereignisse

GET /api/v1/events/sample?type=deal.stage_changed liefert {"events": [ … ]} mit einem Beispiel-Webhook-Umschlag dieses Typs, ohne type je eines pro Typ. Automatisierungstools nutzen das, um Ihnen die Felder zu zeigen, bevor ein echtes Ereignis eintrifft.

Webhooks

GET, POST /api/v1/webhooks und DELETE /api/v1/webhooks/{id} verwalten Ereignis-Abonnements. Siehe Webhooks & Ereignisse.