Leads API

Lesen Sie Leads und aktualisieren Sie ihren Status aus Ihren eigenen Systemen mit einem API-Schlüssel mit begrenzten Rechten.

Diese Seite wurde aus dem Englischen übersetzt. Bei Abweichungen gilt die englische Version. Auf Englisch lesen

Die Leads API lässt Ihr CRM, Ihr Data Warehouse oder Ihre Automatisierung Ihre Leads lesen und ihren Status aktualisieren.

Schlüssel

Erstellen Sie Schlüssel in Studio unter Integrations → Leads API → New key. Jeder Schlüssel hat:

einen Namen;
Berechtigungen: leads:read (Read leads) und optional leads:write-status (Change lead status);
ein Ablaufdatum von 30, 90, 180 Tagen oder 1 Jahr.

Schlüssel sehen aus wie atl_lead_ gefolgt von 43 Zeichen. Sie werden einmal angezeigt, nur als Fingerabdruck gespeichert, bei jeder Anfrage geprüft und können jederzeit widerrufen werden (Revoke key). Eine Site-Umgebung kann bis zu 20 aktive Schlüssel haben. Das Erstellen eines Schlüssels kann eine zweite Bestätigung auf Ihrem Telefon verlangen.

Basis-URL und Authentifizierung

https://<delivery host>/v1/leads-api/environments/{environmentId}
Authorization: Bearer atl_lead_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Antworten haben Cache-Control: private, no-store. Fehler nutzen das Format application/problem+json nach RFC 9457.

Leads auflisten

GET /leads?since=2026-10-01T00:00:00Z&limit=50&cursor=…

Parameter	Hinweise
`since`	Nur Leads, die zu oder nach diesem Zeitpunkt aktualisiert wurden. ISO 8601 mit Zeitzone
`limit`	1 bis 200, Standard 50
`cursor`	Der `nextCursor` aus der vorherigen Antwort

Leads kommen mit der ältesten Änderung zuerst. Die Antwort ist { "leads": [ … ], "nextCursor": "…" | null }. Blättern Sie weiter, bis nextCursor gleich null ist, und speichern Sie das letzte updatedAt, um beim nächsten Mal nur Änderungen abzurufen.

Die Liste enthält zusammengeführte, anonymisierte und Test-Leads. Prüfen Sie mergedInto, anonymisedAt und isTest.

Einen Lead abrufen

GET /leads/{leadId}

Feld	Hinweise
`id`, `source`	Die Quelle ist das Formular oder der Chatbot, aus dem der Lead stammt
`form`	`{ key, name }` oder `null` bei Chatbot-Leads
`name`, `email`, `phone`, `company`, `message`	Leer, nachdem die Aufbewahrung personenbezogene Daten entfernt hat
`details`	Alle weiteren Antworten
`status`	`new`, `contacted`, `qualified`, `won`, `lost` oder `spam`
`isTest`	Testeinsendungen aus Studio
`version`	Senden Sie sie zurück, wenn Sie den Status ändern
`mergedInto`, `anonymisedAt`	Gesetzt, wenn der Lead zusammengeführt oder anonymisiert wurde
`createdAt`, `updatedAt`	ISO-8601-Zeitstempel

Den Status eines Leads ändern

PATCH /leads/{leadId}/status mit { "status": "qualified", "expectedVersion": 4 }. Braucht die Berechtigung Change lead status. Die Änderung erscheint im Verlauf des Leads als vom Schlüssel vorgenommen.

Fehler und Limits

Status	Code	Bedeutung
401	`CP_UNAUTHENTICATED`	Schlüssel fehlt, ist falsch, abgelaufen oder widerrufen
403	`CP_FORBIDDEN`	Dem Schlüssel fehlt die Berechtigung für diese Anfrage
404	`CP_NOT_FOUND`	Kein solcher Lead in dieser Umgebung
409	`CP_VERSION_CONFLICT`	Der Lead hat sich geändert, seit Sie ihn gelesen haben. Lesen Sie ihn erneut
422	`REQUEST_SCHEMA_INVALID`	Der Anfragekörper oder ein Parameter ist ungültig
422	`CURSOR_INVALID`	Der Cursor konnte nicht gelesen werden
429	`RATE_LIMITED`	Mehr als 300 Anfragen pro Minute. Warten Sie und versuchen Sie es erneut

Das Ratenlimit gilt pro Atlas-API-Server, betrachten Sie 300 Anfragen pro Minute daher als Obergrenze, nicht als Garantie.