Conventies

Formaten, id's, tijden, bedragen en de opbouw van verzoeken en antwoorden.

JSON#

Verzoeken en antwoorden zijn JSON in UTF-8. Stuur bij een POST of PATCH altijd Content-Type: application/json mee. Een body mag maximaal 1 MB zijn.

Objecten#

Elk object heeft een veld object met het soort object en een id. Een los object staat onder data:

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

Alle velden van een object zijn altijd aanwezig. Een veld zonder waarde is null; er vallen nooit velden weg.

Id's#

Id's zijn strings. Klanten hebben een UUID. Behandel een id als ondoorzichtige tekst en leid er niets uit af.

Tijden en datums#

Tijden zijn ISO 8601 in UTC, bijvoorbeeld 2026-09-14T10:15:00Z. Datums zonder tijd hebben de vorm 2026-09-14.

Bedragen#

Bedragen zijn decimale strings met twee decimalen, met de valuta erbij: {"total": "1234.50", "currency": "EUR"}. Zo ontstaan er geen afrondingsfouten. Bij invoer mag je ook een getal sturen; meer dan twee decimalen geeft een validatiefout.

Gedeeltelijk bijwerken#

PATCH wijzigt alleen de velden die je meestuurt. Een onbekend veld geeft 422 unknown_field, zodat een tikfout in een veldnaam direct opvalt.

Acties#

Een statuswijziging gaat via een eigen actie-endpoint, bijvoorbeeld POST /customers/{id}/convert. Zo lopen alle regels van Klantly altijd mee, zoals automations en de klanttijdlijn.

Taal#

Foutmeldingen komen in de taal uit Accept-Language (nl, en, de of fr). Stuur je niets mee, dan krijg je de taal van je bedrijf. De code van een fout is altijd Engels.

Request-id#

Elk antwoord heeft een header X-Request-Id. Noem die bij vragen aan support, dan vinden we je verzoek direct terug.

Versies#

Deze documentatie beschrijft versie 1 (/api/v1). Binnen v1 komen er alleen dingen bij: nieuwe endpoints, velden of foutcodes. Maak je koppeling daarom tolerant voor onbekende velden in antwoorden. Alle wijzigingen staan in de changelog.

Laatst bijgewerkt op 14 september 2026