Gut zu wissen: Der API-Zugang gehört zum Tarif PRO. Du findest ihn unter Konto & Lizenz › API-Zugang.
Mit der API liest deine eigene Software — ein Bewerbermanagement, ein CRM, eine Tabelle — die Eingänge deines Betriebs: Bewerbungen, Anfragen und Termine, dazu deine Kampagnen. Mit Webhooks erfährt sie von einem neuen Eingang sofort, ohne ständig nachzufragen.
Die API ist nur lesend: Über sie lässt sich nichts ändern oder löschen.
Schlüssel anlegen
- Konto & Lizenz › API-Zugang öffnen — das darf nur der Inhaber.
- Einen Namen vergeben, zum Beispiel „Anbindung Bewerbermanagement", und Schlüssel anlegen.
- Den Schlüssel (er beginnt mit
ek_) sofort kopieren und in deiner Anbindung hinterlegen. Er steht nur dieses eine Mal da — wir speichern nur eine Prüfsumme und sehen ihn selbst nicht.
Lege für jede Anbindung einen eigenen Schlüssel an. Dann kannst du jede einzeln widerrufen — das wirkt sofort.
Tipp: Ein Schlüssel gehört in die Einstellungen deiner Anbindung, nicht in E-Mails oder Chats. Ist einer irgendwo gelandet, wo er nicht hingehört: widerrufen und einen neuen anlegen.
Anmelden und abfragen
Jede Anfrage trägt den Schlüssel in der Kopfzeile Authorization. Antworten kommen als JSON, Zeitpunkte mit Zeitzone (zum Beispiel 2026-11-11T14:05:00+01:00). Ein Schlüssel sieht nur die Daten deines Betriebs.
| Abfrage | Was zurückkommt |
|---|---|
GET /api/v1 |
wer fragt, die Grenze je Minute, die Endpunkte |
GET /api/v1/kampagnen |
deine Kampagnen — Filter ziel (bewerbung, anfrage, termin, umfrage) und status |
GET /api/v1/bewerbungen |
Bewerbungen, neueste zuerst |
GET /api/v1/anfragen |
Anfragen |
GET /api/v1/termine |
gebuchte Termine |
GET /api/v1/bewerbungen/<id> |
ein einzelner Eingang (ebenso anfragen/<id> und termine/<id>) |
Die drei Eingangs-Listen lassen sich filtern:
kampagne— die Kennung einer Kampagne aus/api/v1/kampagnenstatus— ein Status aus deinem Posteingang, etwaneu. Ein falscher Wert bekommt eine Antwort, die alle erlaubten aufzählt.vonundbis— Tage wie2026-11-30, beide eingeschlossen. Bei Terminen zählt der Tag des Termins, sonst der Tag des Eingangs.seite(ab 1) undpro_seite(bis 100, ohne Angabe 50). Die Antwort nennt dazugesamtundseiten.
Zwei Beispiele
Alle neuen Bewerbungen:
curl -H "Authorization: Bearer ek_…" "https://app.easy-kampagne.de/api/v1/bewerbungen?status=neu"
Alle Termine im Dezember, bis zu 100 auf einer Seite:
curl -H "Authorization: Bearer ek_…" "https://app.easy-kampagne.de/api/v1/termine?von=2026-12-01&bis=2026-12-31&pro_seite=100"
Die Adresse steht in Anführungszeichen — sonst stolpert die Kommandozeile über das ? und das &. Die genaue Adresse für deinen Zugang steht auch unter API-Zugang › So fragst du ab.
Wenn etwas nicht klappt
| Antwort | Bedeutung |
|---|---|
| 400 | Ein Filter stimmt nicht — fehler sagt, welcher und was erlaubt ist |
| 401 | Schlüssel fehlt, ist falsch oder widerrufen |
| 403 | Der Tarif erlaubt die API nicht, oder sie ist für deinen Betrieb nicht freigeschaltet |
| 404 | Diesen Eingang gibt es nicht — oder er gehört nicht zu deinem Betrieb |
| 429 | Zu viele Anfragen: höchstens 120 je Minute und Schlüssel. Retry-After sagt, wie viele Sekunden du warten sollst |
Jede erfolgreiche Antwort trägt X-RateLimit-Limit und X-RateLimit-Remaining — so kann sich deine Anbindung selbst bremsen.
Webhooks
Ein Webhook ist eine Adresse deiner Anbindung, an die wir bei jedem neuen Eingang sofort eine Nachricht schicken.
- Unter API-Zugang › Webhooks die Adresse eintragen — nur
https://— und wählen, bei welchen Eingängen: Bewerbungen, Anfragen, Termine. - Webhook anlegen und das Geheimnis kopieren. Auch das steht nur einmal da; mit Geheimnis neu bekommst du jederzeit ein neues (das alte gilt dann sofort nicht mehr).
- Testereignis senden — im Zustell-Protokoll darunter siehst du gleich, ob deine Adresse geantwortet hat.
Höchstens fünf Webhooks je Betrieb.
Was ankommt
Ein POST mit JSON. In daten steht der Eingang genau so, wie ihn die API unter /api/v1/bewerbungen/<id> (bzw. anfragen, termine) liefert:
{
"ereignis": "eingang.neu",
"zustellung": "0193a6f2-…",
"zeit": "2026-11-11T14:05:00+01:00",
"art": "bewerbung",
"daten": { "id": "…", "name": "…", "status": "neu", "…": "…" }
}
Dazu drei Kopfzeilen:
X-Easy-Ereignis—eingang.neu, beim TestereignistestX-Easy-Zustellung— die Kennung der Zustellung. Bei einer Wiederholung ist sie dieselbe; so erkennst du doppelte.X-Easy-Signatur— die Signatur, siehe unten
Antworte innerhalb von 10 Sekunden mit einem Status von 200 bis 299. Klappt das nicht, versuchen wir es erneut: nach 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden und 12 Stunden. Danach steht die Zustellung als gescheitert im Protokoll. Weiterleitungen folgen wir nicht.
Signatur prüfen
Prüfe jede Nachricht, bevor du ihr traust. Die Kopfzeile sieht so aus:
X-Easy-Signatur: t=1762866300,v1=5f2c8e…
t(die Zeit in Sekunden) undv1aus der Kopfzeile lesen.- HMAC-SHA256 rechnen — über
t, einen Punkt und den Körper der Nachricht, mit deinem Geheimnis als Schlüssel. Den Körper genau so nehmen, wie er ankam, nicht neu formatiert. - Das Ergebnis muss
v1gleichen, undtdarf nicht älter als fünf Minuten sein. Sonst die Nachricht verwerfen.
So sieht das in PHP aus:
$koerper = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_EASY_SIGNATUR'] ?? ''), $sig);
$erwartet = hash_hmac('sha256', ($sig['t'] ?? '').'.'.$koerper, getenv('EASY_WEBHOOK_GEHEIMNIS'));
if (!hash_equals($erwartet, (string) ($sig['v1'] ?? '')) || abs(time() - (int) ($sig['t'] ?? 0)) > 300) {
http_response_code(400);
exit;
}
$nachricht = json_decode($koerper, true);
http_response_code(200);
Das Geheimnis liegt hier in einer Umgebungsvariable — nicht im Programmtext.
Datenschutz
- Anonymisierte Bewerbungen kommen anonymisiert, ohne E-Mail-Adresse. Gelöschte kommen gar nicht mehr — auch keine Wiederholung eines Webhooks.
- Das Zustell-Protokoll zeigt nur, wohin und mit welchem Ergebnis. Den Inhalt eines Eingangs bewahren wir dort nicht auf; jede Nachricht wird beim Versuch frisch gebaut.
- Was deine Anbindung abholt, liegt danach bei dir. Die Löschfristen hier gelten dort nicht von selbst — regle sie in deiner Software genauso.
- Wer wann einen Schlüssel oder Webhook angelegt, widerrufen oder gelöscht hat, steht im Protokoll unter Konto & Lizenz.