Klantly Developers

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.

There are two exceptions. You upload a file as multipart/form-data (attachments on a quote and photos on a work order, up to 10 MB per file), and fetching a PDF returns the file itself instead of JSON. Both are noted with the endpoint in the API reference.

Objects

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

JSON
{
  "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: a UUID (customers, deals, notes, appointments, tasks, work orders, quotes, invoices, orders, conversations, reviews and attachments) or an id with a prefix, such as usr_… for a user, stg_… for a pipeline stage and evt_… for an event. 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 18, 2026