Klantly Developers

Konventionen

Formate, IDs, Zeitangaben, Beträge und der Aufbau von Anfragen und Antworten.

JSON

Anfragen und Antworten sind JSON in UTF-8. Senden Sie bei einem POST oder PATCH immer Content-Type: application/json mit. Ein Body darf höchstens 1 MB groß sein.

Davon gibt es zwei Ausnahmen. Eine Datei laden Sie als multipart/form-data hoch (Anhänge zu einem Angebot und Fotos zu einem Arbeitsauftrag, bis 10 MB pro Datei), und ein PDF abzurufen liefert die Datei selbst statt JSON. Beides steht in der API-Referenz beim jeweiligen Endpunkt.

Objekte

Jedes Objekt hat ein Feld object mit der Art des Objekts und eine id. Ein einzelnes Objekt steht unter data:

JSON
{
  "data": {
    "object": "customer",
    "id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    "email": "jan@example.com"
  }
}

Alle Felder eines Objekts sind immer vorhanden. Ein Feld ohne Wert ist null; Felder fallen nie weg.

IDs

IDs sind Zeichenketten: eine UUID (Kunden, Deals, Notizen, Termine, Aufgaben, Arbeitsaufträge, Angebote, Rechnungen, Bestellungen, Unterhaltungen, Bewertungen und Anhänge) oder eine ID mit Präfix, etwa usr_… für einen Benutzer, stg_… für eine Pipeline-Phase und evt_… für ein Event. Behandeln Sie eine ID als undurchsichtigen Text und leiten Sie nichts daraus ab.

Zeiten und Datumsangaben

Zeiten sind ISO 8601 in UTC, zum Beispiel 2026-09-14T10:15:00Z. Datumsangaben ohne Uhrzeit haben die Form 2026-09-14.

Beträge

Beträge sind Dezimalzeichenketten mit zwei Nachkommastellen, zusammen mit der Währung: {"total": "1234.50", "currency": "EUR"}. So entstehen keine Rundungsfehler. Bei der Eingabe dürfen Sie auch eine Zahl senden; mehr als zwei Nachkommastellen ergeben einen Validierungsfehler.

Teilweise Aktualisierung

PATCH ändert nur die Felder, die Sie mitsenden. Ein unbekanntes Feld ergibt 422 unknown_field, sodass ein Tippfehler in einem Feldnamen sofort auffällt.

Aktionen

Eine Statusänderung läuft über einen eigenen Aktions-Endpunkt, zum Beispiel POST /customers/{id}/convert. So greifen immer alle Regeln von Klantly, etwa Automationen und die Kundenhistorie.

Sprache

Fehlermeldungen erscheinen in der Sprache aus Accept-Language (nl, en, de oder fr). Senden Sie nichts mit, erhalten Sie die Sprache Ihres Unternehmens. Der code eines Fehlers ist immer Englisch.

Request-ID

Jede Antwort hat einen Header X-Request-Id. Nennen Sie ihn bei Fragen an den Support, dann finden wir Ihre Anfrage sofort wieder.

Versionen

Diese Dokumentation beschreibt Version 1 (/api/v1). Innerhalb von v1 kommen nur Dinge hinzu: neue Endpunkte, Felder oder Fehlercodes. Gestalten Sie Ihre Anbindung daher tolerant gegenüber unbekannten Feldern in Antworten. Alle Änderungen stehen im Änderungsprotokoll.

Zuletzt aktualisiert am 18. September 2026