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.

Objekte#

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

{
  "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. Kunden haben eine UUID. 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 14. September 2026