Conventions

Formats, ids, times, amounts and how requests and responses are structured.

JSON#

Requests and responses are JSON in UTF-8. Always send Content-Type: application/json with a POST or PATCH. A body can be at most 1 MB.

Objects#

Every object has an object field with the kind of object, and an id. A single object is returned under data:

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

All fields of an object are always present. A field without a value is null; fields never disappear.

Ids#

Ids are strings. Customers have a UUID. Treat an id as opaque text and do not derive anything from it.

Times and dates#

Times are ISO 8601 in UTC, for example 2026-09-14T10:15:00Z. Dates without a time look like 2026-09-14.

Amounts#

Amounts are decimal strings with two decimals, together with the currency: {"total": "1234.50", "currency": "EUR"}. This avoids rounding errors. As input you may also send a number; more than two decimals is a validation error.

Partial updates#

PATCH only changes the fields you send. An unknown field returns 422 unknown_field, so a typo in a field name is noticed right away.

Actions#

A status change goes through its own action endpoint, for example POST /customers/{id}/convert. That way all of Klantly's rules always apply, such as automations and the customer timeline.

Language#

Error messages use the language from Accept-Language (nl, en, de or fr). If you send nothing, you get your company's language. The code of an error is always English.

Request id#

Every response has an X-Request-Id header. Mention it when you contact support and we will find your request right away.

Versions#

This documentation describes version 1 (/api/v1). Within v1 things are only added: new endpoints, fields or error codes. Make your integration tolerant of unknown fields in responses. All changes are listed in the changelog.

Last updated on September 14, 2026