{ "openapi": "3.1.0", "info": { "title": "Klantly API", "version": "1.0.0", "description": "De publieke API van Klantly. Authenticeer met een API-sleutel als Bearer-token. Gidsen, foutcodes en voorbeelden staan op de developer-portal.", "contact": { "name": "Klantly", "url": "https://developers.klantly.com/nl/support" } }, "externalDocs": { "url": "https://developers.klantly.com/nl", "description": "Klantly Developers" }, "servers": [ { "url": "https://app.klantly.com/api/v1" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "API-sleutel", "description": "Test je verbinding en bekijk welke sleutel, welk bedrijf, welke scopes en welke limieten gelden." }, { "name": "Bedrijf", "description": "De gegevens van je eigen bedrijf: naam, adres, taal en btw-instellingen." }, { "name": "Gebruikers", "description": "De gebruikers van je bedrijf, bijvoorbeeld om een deal aan iemand toe te wijzen." }, { "name": "Klanten", "description": "Klanten en leads: aanmaken, opzoeken, bijwerken en een lead omzetten naar klant." }, { "name": "Notities", "description": "Interne notities bij een klant of een deal. Je klant ziet ze nooit." }, { "name": "Pipelinefasen", "description": "De fasen van je pipelinebord, op volgorde, en of een fase open, gewonnen of verloren betekent." }, { "name": "Deals", "description": "De kaarten op je pipelinebord: aanmaken, bijwerken, naar een andere fase verplaatsen, winnen, verliezen en archiveren." }, { "name": "Webhook-endpoints", "description": "Adressen waar Klantly direct een bericht naartoe stuurt zodra er iets verandert. Ondertekening en herhalingen staan uitgelegd in de gids over webhooks." }, { "name": "Events", "description": "Alles wat er de afgelopen 30 dagen veranderde, als lijst. Om gemiste webhooks in te halen, of om te pollen in plaats van webhooks te gebruiken." } ], "paths": { "/me": { "get": { "operationId": "me", "summary": "Sleutel en bedrijf ophalen", "description": "Geeft de sleutel waarmee je het verzoek doet terug, met het bedrijf, de scopes, de vervaldatum en de limieten. Gebruik dit endpoint om je verbinding te testen: het vraagt geen scope.", "tags": [ "API-sleutel" ], "x-klantly-scope": null, "externalDocs": { "url": "https://developers.klantly.com/nl/reference/api-key#me" }, "responses": { "200": { "description": "Gelukt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } }, "ETag": { "description": "Versie van het object, voor If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ApiKey" } }, "additionalProperties": false }, "example": { "data": { "object": "api_key", "id": "01j7zq3k9x2m4n6p8r0t2v4w6y", "name": "Website", "prefix": "kly_4fZ2mQ8v", "scopes": [ "customers.read", "customers.write" ], "expires_at": "2027-09-14T10:15:00Z", "created_at": "2026-09-14T10:15:00Z", "company": { "object": "company", "id": "42", "name": "De Vries Bouw" }, "rate_limits": [ { "name": "key_minute", "limit": 120, "window_seconds": 60 } ] } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/company": { "get": { "operationId": "companyGet", "summary": "Bedrijf ophalen", "description": "De gegevens van het bedrijf waar de sleutel bij hoort, met de standaard-btw en of prijzen inclusief btw zijn.", "tags": [ "Bedrijf" ], "x-klantly-scope": "company.read", "externalDocs": { "url": "https://developers.klantly.com/nl/reference/company#companyget" }, "responses": { "200": { "description": "Gelukt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } }, "ETag": { "description": "Versie van het object, voor If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Company" } }, "additionalProperties": false }, "example": { "data": { "object": "company", "id": "42", "name": "De Vries Bouw", "email": "info@devriesbouw.nl", "phone": "+31 30 1234567", "website": "https://devriesbouw.nl", "coc_number": "12345678", "vat_number": "NL123456789B01", "address": "Industrieweg 5", "postal_code": "3542 AD", "city": "Utrecht", "country": "NL", "language": "nl", "currency": "EUR", "timezone": "Europe/Amsterdam", "default_vat_rate": "21.00", "prices_include_vat": false } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Deze API-sleutel heeft geen toegang tot deze actie.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Deze API-sleutel heeft geen toegang tot deze actie.", "status": 403, "code": "insufficient_scope", "detail": "Hiervoor is de scope customers.write nodig. Pas de scopes van de sleutel aan in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/users": { "get": { "operationId": "usersList", "summary": "Gebruikers opvragen", "description": "De gebruikers van je bedrijf, op volgorde van id. De id gebruik je als assigned_user_id van een deal.", "tags": [ "Gebruikers" ], "x-klantly-scope": "users.read", "externalDocs": { "url": "https://developers.klantly.com/nl/reference/users#userslist" }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Aantal resultaten per pagina.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "De next_cursor of prev_cursor uit meta van het vorige antwoord.", "schema": { "type": "string" } }, { "name": "filter[status]", "in": "query", "required": false, "description": "Alleen actieve of alleen gedeactiveerde gebruikers.", "schema": { "type": "string", "enum": [ "active", "inactive" ] } } ], "responses": { "200": { "description": "Gelukt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "additionalProperties": false }, "example": { "data": [ { "object": "user", "id": "7", "name": "Sanne Bakker", "email": "sanne@devriesbouw.nl", "role": "Verkoop", "is_owner": false, "status": "active", "created_at": "2026-09-14T10:15:00Z" } ], "meta": { "limit": 50, "next_cursor": "eyJpZCI6IjlkM2Y2YzFlIn0", "prev_cursor": null } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Deze API-sleutel heeft geen toegang tot deze actie.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Deze API-sleutel heeft geen toegang tot deze actie.", "status": 403, "code": "insufficient_scope", "detail": "Hiervoor is de scope customers.write nodig. Pas de scopes van de sleutel aan in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "De invoer is ongeldig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "De invoer is ongeldig.", "status": 422, "code": "validation_failed", "detail": "1 veld is ongeldig.", "errors": { "email": [ "Email moet een geldig e-mailadres zijn." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/customers": { "get": { "operationId": "customersList", "summary": "Klanten opvragen", "description": "Een lijst van klanten en leads, nieuwste eerst. Filter op status, type, e-mailadres of wijzigingsdatum, zoek met q en blader met de cursor uit meta.", "tags": [ "Klanten" ], "x-klantly-scope": "customers.read", "externalDocs": { "url": "https://developers.klantly.com/nl/reference/customers#customerslist" }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Aantal resultaten per pagina.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "De next_cursor of prev_cursor uit meta van het vorige antwoord.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Zoek in naam, e-mailadres, bedrijfsnaam en telefoonnummer.", "schema": { "type": "string", "minLength": 2, "maxLength": 100 } }, { "name": "sort", "in": "query", "required": false, "description": "Sortering op created_at of updated_at; een min-teken ervoor is aflopend.", "schema": { "type": "string", "enum": [ "-created_at", "created_at", "-updated_at", "updated_at" ], "default": "-created_at" } }, { "name": "filter[status]", "in": "query", "required": false, "description": "Alleen leads of alleen klanten.", "schema": { "type": "string", "enum": [ "lead", "customer" ] } }, { "name": "filter[type]", "in": "query", "required": false, "description": "Alleen particulieren of alleen bedrijven.", "schema": { "type": "string", "enum": [ "individual", "business" ] } }, { "name": "filter[email]", "in": "query", "required": false, "description": "Precies dit e-mailadres (hoofdletters maken niet uit).", "schema": { "type": "string", "format": "email" } }, { "name": "filter[updated_since]", "in": "query", "required": false, "description": "Alleen wat sinds dit tijdstip is gewijzigd: ISO 8601 mét tijdzone, bijvoorbeeld 2026-09-14T10:15:00Z. Handig om te synchroniseren.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Gelukt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "additionalProperties": false }, "example": { "data": [ { "object": "customer", "id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "type": "business", "status": "lead", "name": "Jan de Vries", "email": "jan@example.com", "phone": "+31 6 12345678", "company_name": "De Vries Bouw", "vat_number": "NL123456789B01", "coc_number": "12345678", "address": "Dorpsstraat 1", "postal_code": "3511 AB", "city": "Utrecht", "country": "NL", "email_unsubscribed": false, "converted_at": null, "last_activity_at": "2026-09-14T10:15:00Z", "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } ], "meta": { "limit": 50, "next_cursor": "eyJpZCI6IjlkM2Y2YzFlIn0", "prev_cursor": null } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Deze API-sleutel heeft geen toegang tot deze actie.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Deze API-sleutel heeft geen toegang tot deze actie.", "status": 403, "code": "insufficient_scope", "detail": "Hiervoor is de scope customers.write nodig. Pas de scopes van de sleutel aan in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "De invoer is ongeldig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "De invoer is ongeldig.", "status": 422, "code": "validation_failed", "detail": "1 veld is ongeldig.", "errors": { "email": [ "Email moet een geldig e-mailadres zijn." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "post": { "operationId": "customersCreate", "summary": "Klant aanmaken", "description": "Maakt een nieuwe lead aan. Het e-mailadres is verplicht en uniek binnen je bedrijf: een bestaand adres geeft een validatiefout. Automations en de klanttijdlijn werken precies zoals bij aanmaken in Klantly zelf.", "tags": [ "Klanten" ], "x-klantly-scope": "customers.write", "externalDocs": { "url": "https://developers.klantly.com/nl/reference/customers#customerscreate" }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Een unieke sleutel per verzoek (bijvoorbeeld een UUID): een nieuwe poging maakt dan geen dubbel record. 24 uur geldig.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomersCreateRequest" }, "example": { "email": "jan@example.com", "name": "Jan de Vries", "type": "business", "company_name": "De Vries Bouw", "city": "Utrecht" } } } }, "responses": { "201": { "description": "Aangemaakt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } }, "ETag": { "description": "Versie van het object, voor If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Customer" } }, "additionalProperties": false }, "example": { "data": { "object": "customer", "id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "type": "business", "status": "lead", "name": "Jan de Vries", "email": "jan@example.com", "phone": "+31 6 12345678", "company_name": "De Vries Bouw", "vat_number": "NL123456789B01", "coc_number": "12345678", "address": "Dorpsstraat 1", "postal_code": "3511 AB", "city": "Utrecht", "country": "NL", "email_unsubscribed": false, "converted_at": null, "last_activity_at": "2026-09-14T10:15:00Z", "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / limit_reached / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Deze API-sleutel heeft geen toegang tot deze actie.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Deze API-sleutel heeft geen toegang tot deze actie.", "status": 403, "code": "insufficient_scope", "detail": "Hiervoor is de scope customers.write nodig. Pas de scopes van de sleutel aan in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "limit_reached": { "summary": "De limiet van het abonnement is bereikt.", "value": { "type": "https://developers.klantly.com/errors/limit_reached", "title": "De limiet van het abonnement is bereikt.", "status": 403, "code": "limit_reached", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "409": { "description": "idempotency_in_progress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_in_progress": { "summary": "Een verzoek met deze Idempotency-Key is nog bezig.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Een verzoek met deze Idempotency-Key is nog bezig.", "status": 409, "code": "idempotency_in_progress", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "413": { "description": "payload_too_large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payload_too_large": { "summary": "De body van het verzoek is te groot.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "De body van het verzoek is te groot.", "status": 413, "code": "payload_too_large", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "415": { "description": "unsupported_media_type", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unsupported_media_type": { "summary": "Dit formaat wordt niet ondersteund.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Dit formaat wordt niet ondersteund.", "status": 415, "code": "unsupported_media_type", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed / unknown_field / idempotency_key_reused", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "De invoer is ongeldig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "De invoer is ongeldig.", "status": 422, "code": "validation_failed", "detail": "1 veld is ongeldig.", "errors": { "email": [ "Email moet een geldig e-mailadres zijn." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "De invoer bevat een onbekend veld.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "De invoer bevat een onbekend veld.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_key_reused": { "summary": "Deze Idempotency-Key is al gebruikt voor een ander verzoek.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Deze Idempotency-Key is al gebruikt voor een ander verzoek.", "status": 422, "code": "idempotency_key_reused", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/customers/{customer}": { "get": { "operationId": "customersGet", "summary": "Klant ophalen", "description": "Eén klant op id. Het antwoord bevat een ETag die je bij bijwerken in If-Match kunt meesturen.", "tags": [ "Klanten" ], "x-klantly-scope": "customers.read", "externalDocs": { "url": "https://developers.klantly.com/nl/reference/customers#customersget" }, "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "De id (UUID) van de klant.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Gelukt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } }, "ETag": { "description": "Versie van het object, voor If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Customer" } }, "additionalProperties": false }, "example": { "data": { "object": "customer", "id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "type": "business", "status": "lead", "name": "Jan de Vries", "email": "jan@example.com", "phone": "+31 6 12345678", "company_name": "De Vries Bouw", "vat_number": "NL123456789B01", "coc_number": "12345678", "address": "Dorpsstraat 1", "postal_code": "3511 AB", "city": "Utrecht", "country": "NL", "email_unsubscribed": false, "converted_at": null, "last_activity_at": "2026-09-14T10:15:00Z", "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Deze API-sleutel heeft geen toegang tot deze actie.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Deze API-sleutel heeft geen toegang tot deze actie.", "status": 403, "code": "insufficient_scope", "detail": "Hiervoor is de scope customers.write nodig. Pas de scopes van de sleutel aan in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Niet gevonden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Niet gevonden.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "patch": { "operationId": "customersUpdate", "summary": "Klant bijwerken", "description": "Wijzigt alleen de velden die je meestuurt. De status verandert niet via dit endpoint; gebruik daarvoor Lead omzetten naar klant.", "tags": [ "Klanten" ], "x-klantly-scope": "customers.write", "externalDocs": { "url": "https://developers.klantly.com/nl/reference/customers#customersupdate" }, "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "De id (UUID) van de klant.", "schema": { "type": "string", "format": "uuid" } }, { "name": "If-Match", "in": "header", "required": false, "description": "De ETag van de versie die je hebt opgehaald. Is het record intussen gewijzigd, dan volgt 412.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomersUpdateRequest" }, "example": { "phone": "+31 6 12345678", "city": "Amersfoort" } } } }, "responses": { "200": { "description": "Gelukt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } }, "ETag": { "description": "Versie van het object, voor If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Customer" } }, "additionalProperties": false }, "example": { "data": { "object": "customer", "id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "type": "business", "status": "lead", "name": "Jan de Vries", "email": "jan@example.com", "phone": "+31 6 12345678", "company_name": "De Vries Bouw", "vat_number": "NL123456789B01", "coc_number": "12345678", "address": "Dorpsstraat 1", "postal_code": "3511 AB", "city": "Utrecht", "country": "NL", "email_unsubscribed": false, "converted_at": null, "last_activity_at": "2026-09-14T10:15:00Z", "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Deze API-sleutel heeft geen toegang tot deze actie.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Deze API-sleutel heeft geen toegang tot deze actie.", "status": 403, "code": "insufficient_scope", "detail": "Hiervoor is de scope customers.write nodig. Pas de scopes van de sleutel aan in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Niet gevonden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Niet gevonden.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "412": { "description": "precondition_failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "precondition_failed": { "summary": "Het record is intussen gewijzigd.", "value": { "type": "https://developers.klantly.com/errors/precondition_failed", "title": "Het record is intussen gewijzigd.", "status": 412, "code": "precondition_failed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "413": { "description": "payload_too_large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payload_too_large": { "summary": "De body van het verzoek is te groot.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "De body van het verzoek is te groot.", "status": 413, "code": "payload_too_large", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "415": { "description": "unsupported_media_type", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unsupported_media_type": { "summary": "Dit formaat wordt niet ondersteund.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Dit formaat wordt niet ondersteund.", "status": 415, "code": "unsupported_media_type", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed / unknown_field", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "De invoer is ongeldig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "De invoer is ongeldig.", "status": 422, "code": "validation_failed", "detail": "1 veld is ongeldig.", "errors": { "email": [ "Email moet een geldig e-mailadres zijn." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "De invoer bevat een onbekend veld.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "De invoer bevat een onbekend veld.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/customers/{customer}/convert": { "post": { "operationId": "customersConvert", "summary": "Lead omzetten naar klant", "description": "Zet een lead om naar klant. Is het al een klant, dan verandert er niets en krijg je de klant gewoon terug.", "tags": [ "Klanten" ], "x-klantly-scope": "customers.write", "externalDocs": { "url": "https://developers.klantly.com/nl/reference/customers#customersconvert" }, "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "De id (UUID) van de klant.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Een unieke sleutel per verzoek (bijvoorbeeld een UUID): een nieuwe poging maakt dan geen dubbel record. 24 uur geldig.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Gelukt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } }, "ETag": { "description": "Versie van het object, voor If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Customer" } }, "additionalProperties": false }, "example": { "data": { "object": "customer", "id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "type": "business", "status": "lead", "name": "Jan de Vries", "email": "jan@example.com", "phone": "+31 6 12345678", "company_name": "De Vries Bouw", "vat_number": "NL123456789B01", "coc_number": "12345678", "address": "Dorpsstraat 1", "postal_code": "3511 AB", "city": "Utrecht", "country": "NL", "email_unsubscribed": false, "converted_at": null, "last_activity_at": "2026-09-14T10:15:00Z", "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Deze API-sleutel heeft geen toegang tot deze actie.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Deze API-sleutel heeft geen toegang tot deze actie.", "status": 403, "code": "insufficient_scope", "detail": "Hiervoor is de scope customers.write nodig. Pas de scopes van de sleutel aan in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Niet gevonden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Niet gevonden.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "409": { "description": "idempotency_in_progress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_in_progress": { "summary": "Een verzoek met deze Idempotency-Key is nog bezig.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Een verzoek met deze Idempotency-Key is nog bezig.", "status": 409, "code": "idempotency_in_progress", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "idempotency_key_reused", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_key_reused": { "summary": "Deze Idempotency-Key is al gebruikt voor een ander verzoek.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Deze Idempotency-Key is al gebruikt voor een ander verzoek.", "status": 422, "code": "idempotency_key_reused", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/customers/{customer}/activities": { "get": { "operationId": "customersActivities", "summary": "Tijdlijn van een klant", "description": "De tijdlijn van een klant, nieuwste eerst: offertes, facturen, afspraken, e-mails en meer. Verwijzingen naar gekoppelde records staan onder related.", "tags": [ "Klanten" ], "x-klantly-scope": "customers.read", "externalDocs": { "url": "https://developers.klantly.com/nl/reference/customers#customersactivities" }, "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "De id (UUID) van de klant.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Aantal resultaten per pagina.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "De next_cursor of prev_cursor uit meta van het vorige antwoord.", "schema": { "type": "string" } }, { "name": "filter[type]", "in": "query", "required": false, "description": "Alleen activiteiten van dit type, bijvoorbeeld quote_sent of invoice_created.", "schema": { "type": "string", "maxLength": 40 } } ], "responses": { "200": { "description": "Gelukt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerActivity" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "additionalProperties": false }, "example": { "data": [ { "object": "customer_activity", "id": "9d3f7c62-3e7a-4f9d-8c4b-5a6e7f8a9ba3", "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "type": "quote_sent", "title": null, "description": null, "related": { "quote_id": null, "invoice_id": null, "appointment_id": null, "work_order_id": null, "task_id": null, "deal_id": null, "order_id": null, "conversation_id": null }, "happened_at": "2026-09-14T10:15:00Z", "created_at": "2026-09-14T10:15:00Z" } ], "meta": { "limit": 50, "next_cursor": "eyJpZCI6IjlkM2Y2YzFlIn0", "prev_cursor": null } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Deze API-sleutel heeft geen toegang tot deze actie.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Deze API-sleutel heeft geen toegang tot deze actie.", "status": 403, "code": "insufficient_scope", "detail": "Hiervoor is de scope customers.write nodig. Pas de scopes van de sleutel aan in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Niet gevonden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Niet gevonden.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "De invoer is ongeldig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "De invoer is ongeldig.", "status": 422, "code": "validation_failed", "detail": "1 veld is ongeldig.", "errors": { "email": [ "Email moet een geldig e-mailadres zijn." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/customers/{customer}/notes": { "get": { "operationId": "notesListCustomer", "summary": "Notities van een klant opvragen", "description": "De notities bij een klant, nieuwste eerst.", "tags": [ "Notities" ], "x-klantly-scope": "customers.read", "externalDocs": { "url": "https://developers.klantly.com/nl/reference/notes#noteslist-customer" }, "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "De id (UUID) van de klant.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Aantal resultaten per pagina.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "De next_cursor of prev_cursor uit meta van het vorige antwoord.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Gelukt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Note" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "additionalProperties": false }, "example": { "data": [ { "object": "note", "id": "9d3f7b41-2d6f-4e8c-9b3a-4f5d6e7a8b92", "content": "Klant belt terug na de vakantie.", "is_important": true, "parent": { "object": "customer", "id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" }, "author": { "object": "user", "id": "7", "name": "Sanne Bakker" }, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } ], "meta": { "limit": 50, "next_cursor": "eyJpZCI6IjlkM2Y2YzFlIn0", "prev_cursor": null } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Deze API-sleutel heeft geen toegang tot deze actie.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Deze API-sleutel heeft geen toegang tot deze actie.", "status": 403, "code": "insufficient_scope", "detail": "Hiervoor is de scope customers.write nodig. Pas de scopes van de sleutel aan in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Niet gevonden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Niet gevonden.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "De invoer is ongeldig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "De invoer is ongeldig.", "status": 422, "code": "validation_failed", "detail": "1 veld is ongeldig.", "errors": { "email": [ "Email moet een geldig e-mailadres zijn." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "post": { "operationId": "notesCreateCustomer", "summary": "Notitie bij een klant plaatsen", "description": "Plaatst een interne notitie bij een klant. Hij staat daarna direct in Klantly. Een notitie via de API heeft geen auteur.", "tags": [ "Notities" ], "x-klantly-scope": "customers.write", "externalDocs": { "url": "https://developers.klantly.com/nl/reference/notes#notescreate-customer" }, "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "De id (UUID) van de klant.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Een unieke sleutel per verzoek (bijvoorbeeld een UUID): een nieuwe poging maakt dan geen dubbel record. 24 uur geldig.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotesCreateCustomerRequest" }, "example": { "content": "Klant belt terug na de vakantie.", "is_important": true } } } }, "responses": { "201": { "description": "Aangemaakt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } }, "ETag": { "description": "Versie van het object, voor If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Note" } }, "additionalProperties": false }, "example": { "data": { "object": "note", "id": "9d3f7b41-2d6f-4e8c-9b3a-4f5d6e7a8b92", "content": "Klant belt terug na de vakantie.", "is_important": true, "parent": { "object": "customer", "id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" }, "author": { "object": "user", "id": "7", "name": "Sanne Bakker" }, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Deze API-sleutel heeft geen toegang tot deze actie.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Deze API-sleutel heeft geen toegang tot deze actie.", "status": 403, "code": "insufficient_scope", "detail": "Hiervoor is de scope customers.write nodig. Pas de scopes van de sleutel aan in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Niet gevonden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Niet gevonden.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "409": { "description": "idempotency_in_progress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_in_progress": { "summary": "Een verzoek met deze Idempotency-Key is nog bezig.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Een verzoek met deze Idempotency-Key is nog bezig.", "status": 409, "code": "idempotency_in_progress", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "413": { "description": "payload_too_large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payload_too_large": { "summary": "De body van het verzoek is te groot.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "De body van het verzoek is te groot.", "status": 413, "code": "payload_too_large", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "415": { "description": "unsupported_media_type", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unsupported_media_type": { "summary": "Dit formaat wordt niet ondersteund.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Dit formaat wordt niet ondersteund.", "status": 415, "code": "unsupported_media_type", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed / unknown_field / idempotency_key_reused", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "De invoer is ongeldig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "De invoer is ongeldig.", "status": 422, "code": "validation_failed", "detail": "1 veld is ongeldig.", "errors": { "email": [ "Email moet een geldig e-mailadres zijn." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "De invoer bevat een onbekend veld.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "De invoer bevat een onbekend veld.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_key_reused": { "summary": "Deze Idempotency-Key is al gebruikt voor een ander verzoek.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Deze Idempotency-Key is al gebruikt voor een ander verzoek.", "status": 422, "code": "idempotency_key_reused", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/customers/{customer}/notes/{note}": { "patch": { "operationId": "notesUpdateCustomer", "summary": "Notitie bij een klant wijzigen", "description": "Wijzigt alleen de velden die je meestuurt.", "tags": [ "Notities" ], "x-klantly-scope": "customers.write", "externalDocs": { "url": "https://developers.klantly.com/nl/reference/notes#notesupdate-customer" }, "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "De id (UUID) van de klant.", "schema": { "type": "string", "format": "uuid" } }, { "name": "note", "in": "path", "required": true, "description": "De id (UUID) van de notitie.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotesUpdateCustomerRequest" }, "example": { "is_important": false } } } }, "responses": { "200": { "description": "Gelukt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } }, "ETag": { "description": "Versie van het object, voor If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Note" } }, "additionalProperties": false }, "example": { "data": { "object": "note", "id": "9d3f7b41-2d6f-4e8c-9b3a-4f5d6e7a8b92", "content": "Klant belt terug na de vakantie.", "is_important": true, "parent": { "object": "customer", "id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" }, "author": { "object": "user", "id": "7", "name": "Sanne Bakker" }, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Deze API-sleutel heeft geen toegang tot deze actie.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Deze API-sleutel heeft geen toegang tot deze actie.", "status": 403, "code": "insufficient_scope", "detail": "Hiervoor is de scope customers.write nodig. Pas de scopes van de sleutel aan in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Niet gevonden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Niet gevonden.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "413": { "description": "payload_too_large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payload_too_large": { "summary": "De body van het verzoek is te groot.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "De body van het verzoek is te groot.", "status": 413, "code": "payload_too_large", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "415": { "description": "unsupported_media_type", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unsupported_media_type": { "summary": "Dit formaat wordt niet ondersteund.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Dit formaat wordt niet ondersteund.", "status": 415, "code": "unsupported_media_type", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed / unknown_field", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "De invoer is ongeldig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "De invoer is ongeldig.", "status": 422, "code": "validation_failed", "detail": "1 veld is ongeldig.", "errors": { "email": [ "Email moet een geldig e-mailadres zijn." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "De invoer bevat een onbekend veld.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "De invoer bevat een onbekend veld.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "delete": { "operationId": "notesDeleteCustomer", "summary": "Notitie bij een klant verwijderen", "description": "Verwijdert de notitie en de bijlagen ervan. Dit kan niet ongedaan worden gemaakt.", "tags": [ "Notities" ], "x-klantly-scope": "customers.write", "externalDocs": { "url": "https://developers.klantly.com/nl/reference/notes#notesdelete-customer" }, "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "De id (UUID) van de klant.", "schema": { "type": "string", "format": "uuid" } }, { "name": "note", "in": "path", "required": true, "description": "De id (UUID) van de notitie.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Gelukt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } }, "ETag": { "description": "Versie van het object, voor If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DeletedObject" } }, "additionalProperties": false }, "example": { "data": { "object": "note", "id": "9d3f7b41-2d6f-4e8c-9b3a-4f5d6e7a8b92", "deleted": true } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Deze API-sleutel heeft geen toegang tot deze actie.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Deze API-sleutel heeft geen toegang tot deze actie.", "status": 403, "code": "insufficient_scope", "detail": "Hiervoor is de scope customers.write nodig. Pas de scopes van de sleutel aan in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Niet gevonden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Niet gevonden.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals/{deal}/notes": { "get": { "operationId": "notesListDeal", "summary": "Notities van een deal opvragen", "description": "De notities bij een deal, nieuwste eerst.", "tags": [ "Notities" ], "x-klantly-scope": "deals.read", "externalDocs": { "url": "https://developers.klantly.com/nl/reference/notes#noteslist-deal" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "De id (UUID) van de deal.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Aantal resultaten per pagina.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "De next_cursor of prev_cursor uit meta van het vorige antwoord.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Gelukt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Note" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "additionalProperties": false }, "example": { "data": [ { "object": "note", "id": "9d3f7b41-2d6f-4e8c-9b3a-4f5d6e7a8b92", "content": "Klant belt terug na de vakantie.", "is_important": true, "parent": { "object": "customer", "id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" }, "author": { "object": "user", "id": "7", "name": "Sanne Bakker" }, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } ], "meta": { "limit": 50, "next_cursor": "eyJpZCI6IjlkM2Y2YzFlIn0", "prev_cursor": null } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Deze API-sleutel heeft geen toegang tot deze actie.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Deze API-sleutel heeft geen toegang tot deze actie.", "status": 403, "code": "insufficient_scope", "detail": "Hiervoor is de scope customers.write nodig. Pas de scopes van de sleutel aan in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Niet gevonden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Niet gevonden.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "De invoer is ongeldig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "De invoer is ongeldig.", "status": 422, "code": "validation_failed", "detail": "1 veld is ongeldig.", "errors": { "email": [ "Email moet een geldig e-mailadres zijn." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "post": { "operationId": "notesCreateDeal", "summary": "Notitie bij een deal plaatsen", "description": "Plaatst een interne notitie bij een deal. Hij staat daarna direct in Klantly. Een notitie via de API heeft geen auteur.", "tags": [ "Notities" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/nl/reference/notes#notescreate-deal" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "De id (UUID) van de deal.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Een unieke sleutel per verzoek (bijvoorbeeld een UUID): een nieuwe poging maakt dan geen dubbel record. 24 uur geldig.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotesCreateDealRequest" }, "example": { "content": "Klant belt terug na de vakantie.", "is_important": true } } } }, "responses": { "201": { "description": "Aangemaakt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } }, "ETag": { "description": "Versie van het object, voor If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Note" } }, "additionalProperties": false }, "example": { "data": { "object": "note", "id": "9d3f7b41-2d6f-4e8c-9b3a-4f5d6e7a8b92", "content": "Klant belt terug na de vakantie.", "is_important": true, "parent": { "object": "customer", "id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" }, "author": { "object": "user", "id": "7", "name": "Sanne Bakker" }, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Deze API-sleutel heeft geen toegang tot deze actie.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Deze API-sleutel heeft geen toegang tot deze actie.", "status": 403, "code": "insufficient_scope", "detail": "Hiervoor is de scope customers.write nodig. Pas de scopes van de sleutel aan in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Niet gevonden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Niet gevonden.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "409": { "description": "idempotency_in_progress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_in_progress": { "summary": "Een verzoek met deze Idempotency-Key is nog bezig.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Een verzoek met deze Idempotency-Key is nog bezig.", "status": 409, "code": "idempotency_in_progress", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "413": { "description": "payload_too_large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payload_too_large": { "summary": "De body van het verzoek is te groot.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "De body van het verzoek is te groot.", "status": 413, "code": "payload_too_large", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "415": { "description": "unsupported_media_type", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unsupported_media_type": { "summary": "Dit formaat wordt niet ondersteund.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Dit formaat wordt niet ondersteund.", "status": 415, "code": "unsupported_media_type", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed / unknown_field / idempotency_key_reused", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "De invoer is ongeldig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "De invoer is ongeldig.", "status": 422, "code": "validation_failed", "detail": "1 veld is ongeldig.", "errors": { "email": [ "Email moet een geldig e-mailadres zijn." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "De invoer bevat een onbekend veld.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "De invoer bevat een onbekend veld.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_key_reused": { "summary": "Deze Idempotency-Key is al gebruikt voor een ander verzoek.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Deze Idempotency-Key is al gebruikt voor een ander verzoek.", "status": 422, "code": "idempotency_key_reused", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals/{deal}/notes/{note}": { "patch": { "operationId": "notesUpdateDeal", "summary": "Notitie bij een deal wijzigen", "description": "Wijzigt alleen de velden die je meestuurt.", "tags": [ "Notities" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/nl/reference/notes#notesupdate-deal" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "De id (UUID) van de deal.", "schema": { "type": "string", "format": "uuid" } }, { "name": "note", "in": "path", "required": true, "description": "De id (UUID) van de notitie.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotesUpdateDealRequest" }, "example": { "is_important": false } } } }, "responses": { "200": { "description": "Gelukt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } }, "ETag": { "description": "Versie van het object, voor If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Note" } }, "additionalProperties": false }, "example": { "data": { "object": "note", "id": "9d3f7b41-2d6f-4e8c-9b3a-4f5d6e7a8b92", "content": "Klant belt terug na de vakantie.", "is_important": true, "parent": { "object": "customer", "id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" }, "author": { "object": "user", "id": "7", "name": "Sanne Bakker" }, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Deze API-sleutel heeft geen toegang tot deze actie.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Deze API-sleutel heeft geen toegang tot deze actie.", "status": 403, "code": "insufficient_scope", "detail": "Hiervoor is de scope customers.write nodig. Pas de scopes van de sleutel aan in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Niet gevonden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Niet gevonden.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "413": { "description": "payload_too_large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payload_too_large": { "summary": "De body van het verzoek is te groot.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "De body van het verzoek is te groot.", "status": 413, "code": "payload_too_large", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "415": { "description": "unsupported_media_type", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unsupported_media_type": { "summary": "Dit formaat wordt niet ondersteund.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Dit formaat wordt niet ondersteund.", "status": 415, "code": "unsupported_media_type", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed / unknown_field", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "De invoer is ongeldig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "De invoer is ongeldig.", "status": 422, "code": "validation_failed", "detail": "1 veld is ongeldig.", "errors": { "email": [ "Email moet een geldig e-mailadres zijn." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "De invoer bevat een onbekend veld.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "De invoer bevat een onbekend veld.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "delete": { "operationId": "notesDeleteDeal", "summary": "Notitie bij een deal verwijderen", "description": "Verwijdert de notitie en de bijlagen ervan. Dit kan niet ongedaan worden gemaakt.", "tags": [ "Notities" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/nl/reference/notes#notesdelete-deal" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "De id (UUID) van de deal.", "schema": { "type": "string", "format": "uuid" } }, { "name": "note", "in": "path", "required": true, "description": "De id (UUID) van de notitie.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Gelukt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } }, "ETag": { "description": "Versie van het object, voor If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DeletedObject" } }, "additionalProperties": false }, "example": { "data": { "object": "note", "id": "9d3f7b41-2d6f-4e8c-9b3a-4f5d6e7a8b92", "deleted": true } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Deze API-sleutel heeft geen toegang tot deze actie.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Deze API-sleutel heeft geen toegang tot deze actie.", "status": 403, "code": "insufficient_scope", "detail": "Hiervoor is de scope customers.write nodig. Pas de scopes van de sleutel aan in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Niet gevonden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Niet gevonden.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/pipeline-stages": { "get": { "operationId": "pipelineStagesList", "summary": "Pipelinefasen opvragen", "description": "Alle actieve fasen van het pipelinebord, in de volgorde van het bord. De namen in alle vier de talen staan onder names.", "tags": [ "Pipelinefasen" ], "x-klantly-scope": "deals.read", "externalDocs": { "url": "https://developers.klantly.com/nl/reference/pipeline-stages#pipeline-stageslist" }, "responses": { "200": { "description": "Gelukt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PipelineStage" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "additionalProperties": false }, "example": { "data": [ { "object": "pipeline_stage", "id": "3", "name": "Offerte verstuurd", "names": { "nl": "Offerte verstuurd", "en": "Quote sent", "de": "Angebot gesendet", "fr": "Devis envoyé" }, "type": "open", "is_default": false, "position": 3, "probability": "50.00", "color": "#3B82F6" } ], "meta": { "limit": 50, "next_cursor": "eyJpZCI6IjlkM2Y2YzFlIn0", "prev_cursor": null } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Deze API-sleutel heeft geen toegang tot deze actie.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Deze API-sleutel heeft geen toegang tot deze actie.", "status": 403, "code": "insufficient_scope", "detail": "Hiervoor is de scope customers.write nodig. Pas de scopes van de sleutel aan in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals": { "get": { "operationId": "dealsList", "summary": "Deals opvragen", "description": "Een lijst van deals, nieuwste eerst. Gearchiveerde deals staan er standaard niet in; gebruik daarvoor filter[archived]. Filter op status, fase, klant, eigenaar of wijzigingsdatum.", "tags": [ "Deals" ], "x-klantly-scope": "deals.read", "externalDocs": { "url": "https://developers.klantly.com/nl/reference/deals#dealslist" }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Aantal resultaten per pagina.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "De next_cursor of prev_cursor uit meta van het vorige antwoord.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sortering op created_at, updated_at of stage_changed_at; een min-teken ervoor is aflopend.", "schema": { "type": "string", "enum": [ "-created_at", "created_at", "-updated_at", "updated_at", "-stage_changed_at", "stage_changed_at" ], "default": "-created_at" } }, { "name": "filter[status]", "in": "query", "required": false, "description": "Alleen open, gewonnen of verloren deals.", "schema": { "type": "string", "enum": [ "open", "won", "lost" ] } }, { "name": "filter[stage_id]", "in": "query", "required": false, "description": "Alleen deals in deze fase (de id uit Pipelinefasen opvragen).", "schema": { "type": "integer" } }, { "name": "filter[customer_id]", "in": "query", "required": false, "description": "Alleen deals van deze klant.", "schema": { "type": "string", "format": "uuid" } }, { "name": "filter[assigned_user_id]", "in": "query", "required": false, "description": "Alleen deals van deze gebruiker.", "schema": { "type": "integer" } }, { "name": "filter[archived]", "in": "query", "required": false, "description": "false (standaard) toont alleen deals op het bord, true alleen gearchiveerde, all allebei.", "schema": { "type": "string", "enum": [ "false", "true", "all" ], "default": "false" } }, { "name": "filter[updated_since]", "in": "query", "required": false, "description": "Alleen wat sinds dit tijdstip is gewijzigd: ISO 8601 mét tijdzone, bijvoorbeeld 2026-09-14T10:15:00Z. Handig om te synchroniseren.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Gelukt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Deal" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "additionalProperties": false }, "example": { "data": [ { "object": "deal", "id": "9d3f7a20-1c5e-4d7b-8a2f-3e4c5d6f7a81", "title": "Veranda 5x3 m", "description": null, "status": "open", "value": "8450.00", "currency": "EUR", "value_source": "manual", "stage": { "object": "pipeline_stage", "id": "3" }, "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "assigned_user_id": "7", "source": "api", "lost_reason": null, "is_archived": false, "stage_changed_at": "2026-09-14T10:15:00Z", "won_at": null, "lost_at": null, "archived_at": null, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } ], "meta": { "limit": 50, "next_cursor": "eyJpZCI6IjlkM2Y2YzFlIn0", "prev_cursor": null } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Deze API-sleutel heeft geen toegang tot deze actie.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Deze API-sleutel heeft geen toegang tot deze actie.", "status": 403, "code": "insufficient_scope", "detail": "Hiervoor is de scope customers.write nodig. Pas de scopes van de sleutel aan in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "De invoer is ongeldig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "De invoer is ongeldig.", "status": 422, "code": "validation_failed", "detail": "1 veld is ongeldig.", "errors": { "email": [ "Email moet een geldig e-mailadres zijn." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "post": { "operationId": "dealsCreate", "summary": "Deal aanmaken", "description": "Zet een klant op het pipelinebord. Een klant kan maar één open deal tegelijk hebben: heeft hij er al een, dan volgt 409 met de id van die deal in deal_id. Zonder stage_id komt de deal in de standaardfase. Stuur je value mee, dan houdt Klantly dat bedrag vast in plaats van het uit de offertes te berekenen.", "tags": [ "Deals" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/nl/reference/deals#dealscreate" }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Een unieke sleutel per verzoek (bijvoorbeeld een UUID): een nieuwe poging maakt dan geen dubbel record. 24 uur geldig.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealsCreateRequest" }, "example": { "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "title": "Veranda 5x3 m", "value": "8450.00" } } } }, "responses": { "201": { "description": "Aangemaakt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } }, "ETag": { "description": "Versie van het object, voor If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Deal" } }, "additionalProperties": false }, "example": { "data": { "object": "deal", "id": "9d3f7a20-1c5e-4d7b-8a2f-3e4c5d6f7a81", "title": "Veranda 5x3 m", "description": null, "status": "open", "value": "8450.00", "currency": "EUR", "value_source": "manual", "stage": { "object": "pipeline_stage", "id": "3" }, "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "assigned_user_id": "7", "source": "api", "lost_reason": null, "is_archived": false, "stage_changed_at": "2026-09-14T10:15:00Z", "won_at": null, "lost_at": null, "archived_at": null, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Deze API-sleutel heeft geen toegang tot deze actie.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Deze API-sleutel heeft geen toegang tot deze actie.", "status": 403, "code": "insufficient_scope", "detail": "Hiervoor is de scope customers.write nodig. Pas de scopes van de sleutel aan in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "409": { "description": "conflict / idempotency_in_progress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "conflict": { "summary": "Dit botst met de huidige toestand.", "value": { "type": "https://developers.klantly.com/errors/conflict", "title": "Dit botst met de huidige toestand.", "status": 409, "code": "conflict", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_in_progress": { "summary": "Een verzoek met deze Idempotency-Key is nog bezig.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Een verzoek met deze Idempotency-Key is nog bezig.", "status": 409, "code": "idempotency_in_progress", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "413": { "description": "payload_too_large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payload_too_large": { "summary": "De body van het verzoek is te groot.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "De body van het verzoek is te groot.", "status": 413, "code": "payload_too_large", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "415": { "description": "unsupported_media_type", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unsupported_media_type": { "summary": "Dit formaat wordt niet ondersteund.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Dit formaat wordt niet ondersteund.", "status": 415, "code": "unsupported_media_type", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed / unknown_field / idempotency_key_reused", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "De invoer is ongeldig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "De invoer is ongeldig.", "status": 422, "code": "validation_failed", "detail": "1 veld is ongeldig.", "errors": { "email": [ "Email moet een geldig e-mailadres zijn." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "De invoer bevat een onbekend veld.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "De invoer bevat een onbekend veld.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_key_reused": { "summary": "Deze Idempotency-Key is al gebruikt voor een ander verzoek.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Deze Idempotency-Key is al gebruikt voor een ander verzoek.", "status": 422, "code": "idempotency_key_reused", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals/{deal}": { "get": { "operationId": "dealsGet", "summary": "Deal ophalen", "description": "Eén deal op id. Het antwoord bevat een ETag die je bij bijwerken in If-Match kunt meesturen.", "tags": [ "Deals" ], "x-klantly-scope": "deals.read", "externalDocs": { "url": "https://developers.klantly.com/nl/reference/deals#dealsget" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "De id (UUID) van de deal.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Gelukt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } }, "ETag": { "description": "Versie van het object, voor If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Deal" } }, "additionalProperties": false }, "example": { "data": { "object": "deal", "id": "9d3f7a20-1c5e-4d7b-8a2f-3e4c5d6f7a81", "title": "Veranda 5x3 m", "description": null, "status": "open", "value": "8450.00", "currency": "EUR", "value_source": "manual", "stage": { "object": "pipeline_stage", "id": "3" }, "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "assigned_user_id": "7", "source": "api", "lost_reason": null, "is_archived": false, "stage_changed_at": "2026-09-14T10:15:00Z", "won_at": null, "lost_at": null, "archived_at": null, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Deze API-sleutel heeft geen toegang tot deze actie.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Deze API-sleutel heeft geen toegang tot deze actie.", "status": 403, "code": "insufficient_scope", "detail": "Hiervoor is de scope customers.write nodig. Pas de scopes van de sleutel aan in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Niet gevonden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Niet gevonden.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "patch": { "operationId": "dealsUpdate", "summary": "Deal bijwerken", "description": "Wijzigt alleen de velden die je meestuurt. De fase verander je met verplaatsen, winnen of verliezen. Een meegestuurde value zet value_source op manual.", "tags": [ "Deals" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/nl/reference/deals#dealsupdate" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "De id (UUID) van de deal.", "schema": { "type": "string", "format": "uuid" } }, { "name": "If-Match", "in": "header", "required": false, "description": "De ETag van de versie die je hebt opgehaald. Is het record intussen gewijzigd, dan volgt 412.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealsUpdateRequest" }, "example": { "value": "9100.00", "assigned_user_id": 7 } } } }, "responses": { "200": { "description": "Gelukt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } }, "ETag": { "description": "Versie van het object, voor If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Deal" } }, "additionalProperties": false }, "example": { "data": { "object": "deal", "id": "9d3f7a20-1c5e-4d7b-8a2f-3e4c5d6f7a81", "title": "Veranda 5x3 m", "description": null, "status": "open", "value": "8450.00", "currency": "EUR", "value_source": "manual", "stage": { "object": "pipeline_stage", "id": "3" }, "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "assigned_user_id": "7", "source": "api", "lost_reason": null, "is_archived": false, "stage_changed_at": "2026-09-14T10:15:00Z", "won_at": null, "lost_at": null, "archived_at": null, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Deze API-sleutel heeft geen toegang tot deze actie.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Deze API-sleutel heeft geen toegang tot deze actie.", "status": 403, "code": "insufficient_scope", "detail": "Hiervoor is de scope customers.write nodig. Pas de scopes van de sleutel aan in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Niet gevonden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Niet gevonden.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "412": { "description": "precondition_failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "precondition_failed": { "summary": "Het record is intussen gewijzigd.", "value": { "type": "https://developers.klantly.com/errors/precondition_failed", "title": "Het record is intussen gewijzigd.", "status": 412, "code": "precondition_failed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "413": { "description": "payload_too_large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payload_too_large": { "summary": "De body van het verzoek is te groot.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "De body van het verzoek is te groot.", "status": 413, "code": "payload_too_large", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "415": { "description": "unsupported_media_type", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unsupported_media_type": { "summary": "Dit formaat wordt niet ondersteund.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Dit formaat wordt niet ondersteund.", "status": 415, "code": "unsupported_media_type", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed / unknown_field", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "De invoer is ongeldig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "De invoer is ongeldig.", "status": 422, "code": "validation_failed", "detail": "1 veld is ongeldig.", "errors": { "email": [ "Email moet een geldig e-mailadres zijn." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "De invoer bevat een onbekend veld.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "De invoer bevat een onbekend veld.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals/{deal}/move": { "post": { "operationId": "dealsMove", "summary": "Deal verplaatsen", "description": "Verplaatst de deal naar een andere fase, precies zoals slepen op het bord. Is dat een gewonnen of verloren fase, dan wordt de deal ook gewonnen of verloren.", "tags": [ "Deals" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/nl/reference/deals#dealsmove" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "De id (UUID) van de deal.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Een unieke sleutel per verzoek (bijvoorbeeld een UUID): een nieuwe poging maakt dan geen dubbel record. 24 uur geldig.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealsMoveRequest" }, "example": { "stage_id": 3 } } } }, "responses": { "200": { "description": "Gelukt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } }, "ETag": { "description": "Versie van het object, voor If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Deal" } }, "additionalProperties": false }, "example": { "data": { "object": "deal", "id": "9d3f7a20-1c5e-4d7b-8a2f-3e4c5d6f7a81", "title": "Veranda 5x3 m", "description": null, "status": "open", "value": "8450.00", "currency": "EUR", "value_source": "manual", "stage": { "object": "pipeline_stage", "id": "3" }, "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "assigned_user_id": "7", "source": "api", "lost_reason": null, "is_archived": false, "stage_changed_at": "2026-09-14T10:15:00Z", "won_at": null, "lost_at": null, "archived_at": null, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Deze API-sleutel heeft geen toegang tot deze actie.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Deze API-sleutel heeft geen toegang tot deze actie.", "status": 403, "code": "insufficient_scope", "detail": "Hiervoor is de scope customers.write nodig. Pas de scopes van de sleutel aan in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Niet gevonden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Niet gevonden.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "409": { "description": "idempotency_in_progress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_in_progress": { "summary": "Een verzoek met deze Idempotency-Key is nog bezig.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Een verzoek met deze Idempotency-Key is nog bezig.", "status": 409, "code": "idempotency_in_progress", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "413": { "description": "payload_too_large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payload_too_large": { "summary": "De body van het verzoek is te groot.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "De body van het verzoek is te groot.", "status": 413, "code": "payload_too_large", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "415": { "description": "unsupported_media_type", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unsupported_media_type": { "summary": "Dit formaat wordt niet ondersteund.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Dit formaat wordt niet ondersteund.", "status": 415, "code": "unsupported_media_type", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed / unknown_field / idempotency_key_reused", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "De invoer is ongeldig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "De invoer is ongeldig.", "status": 422, "code": "validation_failed", "detail": "1 veld is ongeldig.", "errors": { "email": [ "Email moet een geldig e-mailadres zijn." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "De invoer bevat een onbekend veld.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "De invoer bevat een onbekend veld.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_key_reused": { "summary": "Deze Idempotency-Key is al gebruikt voor een ander verzoek.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Deze Idempotency-Key is al gebruikt voor een ander verzoek.", "status": 422, "code": "idempotency_key_reused", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals/{deal}/win": { "post": { "operationId": "dealsWin", "summary": "Deal winnen", "description": "Verplaatst de deal naar de fase die je bedrijf als gewonnen heeft ingesteld. Is hij al gewonnen, dan verandert er niets.", "tags": [ "Deals" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/nl/reference/deals#dealswin" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "De id (UUID) van de deal.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Een unieke sleutel per verzoek (bijvoorbeeld een UUID): een nieuwe poging maakt dan geen dubbel record. 24 uur geldig.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Gelukt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } }, "ETag": { "description": "Versie van het object, voor If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Deal" } }, "additionalProperties": false }, "example": { "data": { "object": "deal", "id": "9d3f7a20-1c5e-4d7b-8a2f-3e4c5d6f7a81", "title": "Veranda 5x3 m", "description": null, "status": "open", "value": "8450.00", "currency": "EUR", "value_source": "manual", "stage": { "object": "pipeline_stage", "id": "3" }, "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "assigned_user_id": "7", "source": "api", "lost_reason": null, "is_archived": false, "stage_changed_at": "2026-09-14T10:15:00Z", "won_at": null, "lost_at": null, "archived_at": null, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Deze API-sleutel heeft geen toegang tot deze actie.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Deze API-sleutel heeft geen toegang tot deze actie.", "status": 403, "code": "insufficient_scope", "detail": "Hiervoor is de scope customers.write nodig. Pas de scopes van de sleutel aan in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Niet gevonden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Niet gevonden.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "409": { "description": "invalid_state_transition / idempotency_in_progress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_state_transition": { "summary": "Deze actie kan niet in de huidige status.", "value": { "type": "https://developers.klantly.com/errors/invalid_state_transition", "title": "Deze actie kan niet in de huidige status.", "status": 409, "code": "invalid_state_transition", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_in_progress": { "summary": "Een verzoek met deze Idempotency-Key is nog bezig.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Een verzoek met deze Idempotency-Key is nog bezig.", "status": 409, "code": "idempotency_in_progress", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "idempotency_key_reused", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_key_reused": { "summary": "Deze Idempotency-Key is al gebruikt voor een ander verzoek.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Deze Idempotency-Key is al gebruikt voor een ander verzoek.", "status": 422, "code": "idempotency_key_reused", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals/{deal}/lose": { "post": { "operationId": "dealsLose", "summary": "Deal verliezen", "description": "Verplaatst de deal naar de fase die je bedrijf als verloren heeft ingesteld, met optioneel een reden.", "tags": [ "Deals" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/nl/reference/deals#dealslose" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "De id (UUID) van de deal.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Een unieke sleutel per verzoek (bijvoorbeeld een UUID): een nieuwe poging maakt dan geen dubbel record. 24 uur geldig.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealsLoseRequest" }, "example": { "lost_reason": "Te duur" } } } }, "responses": { "200": { "description": "Gelukt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } }, "ETag": { "description": "Versie van het object, voor If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Deal" } }, "additionalProperties": false }, "example": { "data": { "object": "deal", "id": "9d3f7a20-1c5e-4d7b-8a2f-3e4c5d6f7a81", "title": "Veranda 5x3 m", "description": null, "status": "open", "value": "8450.00", "currency": "EUR", "value_source": "manual", "stage": { "object": "pipeline_stage", "id": "3" }, "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "assigned_user_id": "7", "source": "api", "lost_reason": null, "is_archived": false, "stage_changed_at": "2026-09-14T10:15:00Z", "won_at": null, "lost_at": null, "archived_at": null, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Deze API-sleutel heeft geen toegang tot deze actie.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Deze API-sleutel heeft geen toegang tot deze actie.", "status": 403, "code": "insufficient_scope", "detail": "Hiervoor is de scope customers.write nodig. Pas de scopes van de sleutel aan in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Niet gevonden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Niet gevonden.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "409": { "description": "invalid_state_transition / idempotency_in_progress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_state_transition": { "summary": "Deze actie kan niet in de huidige status.", "value": { "type": "https://developers.klantly.com/errors/invalid_state_transition", "title": "Deze actie kan niet in de huidige status.", "status": 409, "code": "invalid_state_transition", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_in_progress": { "summary": "Een verzoek met deze Idempotency-Key is nog bezig.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Een verzoek met deze Idempotency-Key is nog bezig.", "status": 409, "code": "idempotency_in_progress", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "413": { "description": "payload_too_large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payload_too_large": { "summary": "De body van het verzoek is te groot.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "De body van het verzoek is te groot.", "status": 413, "code": "payload_too_large", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "415": { "description": "unsupported_media_type", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unsupported_media_type": { "summary": "Dit formaat wordt niet ondersteund.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Dit formaat wordt niet ondersteund.", "status": 415, "code": "unsupported_media_type", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed / unknown_field / idempotency_key_reused", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "De invoer is ongeldig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "De invoer is ongeldig.", "status": 422, "code": "validation_failed", "detail": "1 veld is ongeldig.", "errors": { "email": [ "Email moet een geldig e-mailadres zijn." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "De invoer bevat een onbekend veld.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "De invoer bevat een onbekend veld.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_key_reused": { "summary": "Deze Idempotency-Key is al gebruikt voor een ander verzoek.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Deze Idempotency-Key is al gebruikt voor een ander verzoek.", "status": 422, "code": "idempotency_key_reused", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals/{deal}/archive": { "post": { "operationId": "dealsArchive", "summary": "Deal archiveren", "description": "Haalt de deal van het bord zonder hem te verwijderen. Deals verwijderen kan niet via de API.", "tags": [ "Deals" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/nl/reference/deals#dealsarchive" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "De id (UUID) van de deal.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Een unieke sleutel per verzoek (bijvoorbeeld een UUID): een nieuwe poging maakt dan geen dubbel record. 24 uur geldig.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Gelukt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } }, "ETag": { "description": "Versie van het object, voor If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Deal" } }, "additionalProperties": false }, "example": { "data": { "object": "deal", "id": "9d3f7a20-1c5e-4d7b-8a2f-3e4c5d6f7a81", "title": "Veranda 5x3 m", "description": null, "status": "open", "value": "8450.00", "currency": "EUR", "value_source": "manual", "stage": { "object": "pipeline_stage", "id": "3" }, "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "assigned_user_id": "7", "source": "api", "lost_reason": null, "is_archived": false, "stage_changed_at": "2026-09-14T10:15:00Z", "won_at": null, "lost_at": null, "archived_at": null, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Deze API-sleutel heeft geen toegang tot deze actie.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Deze API-sleutel heeft geen toegang tot deze actie.", "status": 403, "code": "insufficient_scope", "detail": "Hiervoor is de scope customers.write nodig. Pas de scopes van de sleutel aan in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Niet gevonden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Niet gevonden.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "409": { "description": "idempotency_in_progress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_in_progress": { "summary": "Een verzoek met deze Idempotency-Key is nog bezig.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Een verzoek met deze Idempotency-Key is nog bezig.", "status": 409, "code": "idempotency_in_progress", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "idempotency_key_reused", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_key_reused": { "summary": "Deze Idempotency-Key is al gebruikt voor een ander verzoek.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Deze Idempotency-Key is al gebruikt voor een ander verzoek.", "status": 422, "code": "idempotency_key_reused", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals/{deal}/unarchive": { "post": { "operationId": "dealsUnarchive", "summary": "Deal terugzetten", "description": "Zet een gearchiveerde deal terug op het bord.", "tags": [ "Deals" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/nl/reference/deals#dealsunarchive" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "De id (UUID) van de deal.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Een unieke sleutel per verzoek (bijvoorbeeld een UUID): een nieuwe poging maakt dan geen dubbel record. 24 uur geldig.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Gelukt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } }, "ETag": { "description": "Versie van het object, voor If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Deal" } }, "additionalProperties": false }, "example": { "data": { "object": "deal", "id": "9d3f7a20-1c5e-4d7b-8a2f-3e4c5d6f7a81", "title": "Veranda 5x3 m", "description": null, "status": "open", "value": "8450.00", "currency": "EUR", "value_source": "manual", "stage": { "object": "pipeline_stage", "id": "3" }, "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "assigned_user_id": "7", "source": "api", "lost_reason": null, "is_archived": false, "stage_changed_at": "2026-09-14T10:15:00Z", "won_at": null, "lost_at": null, "archived_at": null, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Deze API-sleutel heeft geen toegang tot deze actie.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Deze API-sleutel heeft geen toegang tot deze actie.", "status": 403, "code": "insufficient_scope", "detail": "Hiervoor is de scope customers.write nodig. Pas de scopes van de sleutel aan in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Niet gevonden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Niet gevonden.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "409": { "description": "idempotency_in_progress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_in_progress": { "summary": "Een verzoek met deze Idempotency-Key is nog bezig.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Een verzoek met deze Idempotency-Key is nog bezig.", "status": 409, "code": "idempotency_in_progress", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "idempotency_key_reused", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_key_reused": { "summary": "Deze Idempotency-Key is al gebruikt voor een ander verzoek.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Deze Idempotency-Key is al gebruikt voor een ander verzoek.", "status": 422, "code": "idempotency_key_reused", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/webhook-endpoints": { "get": { "operationId": "webhookEndpointsList", "summary": "Webhook-endpoints opvragen", "description": "Alle webhook-endpoints van je bedrijf, oudste eerst. Het secret staat er nooit in.", "tags": [ "Webhook-endpoints" ], "x-klantly-scope": "webhooks.manage", "externalDocs": { "url": "https://developers.klantly.com/nl/reference/webhook-endpoints#webhook-endpointslist" }, "responses": { "200": { "description": "Gelukt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "additionalProperties": false }, "example": { "data": [ { "object": "webhook_endpoint", "id": "01j7zr8m2k4n6p8r0t2v4w6y8a", "url": "https://example.com/webhooks/klantly", "description": "Boekhouding", "events": [ "customer.created", "deal.won" ], "status": "active", "disabled_reason": null, "disabled_at": null, "previous_secret_expires_at": null, "last_success_at": "2026-09-14T10:15:02Z", "last_failure_at": null, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } ], "meta": { "limit": 50, "next_cursor": "eyJpZCI6IjlkM2Y2YzFlIn0", "prev_cursor": null } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Deze API-sleutel heeft geen toegang tot deze actie.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Deze API-sleutel heeft geen toegang tot deze actie.", "status": 403, "code": "insufficient_scope", "detail": "Hiervoor is de scope customers.write nodig. Pas de scopes van de sleutel aan in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "post": { "operationId": "webhookEndpointsCreate", "summary": "Webhook-endpoint aanmaken", "description": "Registreert een https-adres dat events ontvangt. Het antwoord bevat het secret om de handtekening te controleren: bewaar het direct, je ziet het hierna niet meer. Je kunt alleen events kiezen over gegevens waar je sleutel leesrecht op heeft; * betekent alle events die daaronder vallen, ook toekomstige. Maximaal 10 endpoints per bedrijf.", "tags": [ "Webhook-endpoints" ], "x-klantly-scope": "webhooks.manage", "externalDocs": { "url": "https://developers.klantly.com/nl/reference/webhook-endpoints#webhook-endpointscreate" }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Een unieke sleutel per verzoek (bijvoorbeeld een UUID): een nieuwe poging maakt dan geen dubbel record. 24 uur geldig.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointsCreateRequest" }, "example": { "url": "https://example.com/webhooks/klantly", "description": "Boekhouding", "events": [ "customer.created", "deal.won" ] } } } }, "responses": { "201": { "description": "Aangemaakt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } }, "ETag": { "description": "Versie van het object, voor If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpointWithSecret" } }, "additionalProperties": false }, "example": { "data": { "object": "webhook_endpoint", "id": "01j7zr8m2k4n6p8r0t2v4w6y8a", "url": "https://example.com/webhooks/klantly", "description": "Boekhouding", "events": [ "customer.created", "deal.won" ], "status": "active", "disabled_reason": null, "disabled_at": null, "previous_secret_expires_at": null, "last_success_at": "2026-09-14T10:15:02Z", "last_failure_at": null, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z", "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / limit_reached / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Deze API-sleutel heeft geen toegang tot deze actie.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Deze API-sleutel heeft geen toegang tot deze actie.", "status": 403, "code": "insufficient_scope", "detail": "Hiervoor is de scope customers.write nodig. Pas de scopes van de sleutel aan in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "limit_reached": { "summary": "De limiet van het abonnement is bereikt.", "value": { "type": "https://developers.klantly.com/errors/limit_reached", "title": "De limiet van het abonnement is bereikt.", "status": 403, "code": "limit_reached", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "409": { "description": "idempotency_in_progress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_in_progress": { "summary": "Een verzoek met deze Idempotency-Key is nog bezig.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Een verzoek met deze Idempotency-Key is nog bezig.", "status": 409, "code": "idempotency_in_progress", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "413": { "description": "payload_too_large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payload_too_large": { "summary": "De body van het verzoek is te groot.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "De body van het verzoek is te groot.", "status": 413, "code": "payload_too_large", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "415": { "description": "unsupported_media_type", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unsupported_media_type": { "summary": "Dit formaat wordt niet ondersteund.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Dit formaat wordt niet ondersteund.", "status": 415, "code": "unsupported_media_type", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed / unknown_field / idempotency_key_reused", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "De invoer is ongeldig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "De invoer is ongeldig.", "status": 422, "code": "validation_failed", "detail": "1 veld is ongeldig.", "errors": { "email": [ "Email moet een geldig e-mailadres zijn." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "De invoer bevat een onbekend veld.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "De invoer bevat een onbekend veld.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_key_reused": { "summary": "Deze Idempotency-Key is al gebruikt voor een ander verzoek.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Deze Idempotency-Key is al gebruikt voor een ander verzoek.", "status": 422, "code": "idempotency_key_reused", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/webhook-endpoints/{endpoint}": { "get": { "operationId": "webhookEndpointsGet", "summary": "Webhook-endpoint ophalen", "description": "Eén endpoint op id, met de status en het tijdstip van de laatste geslaagde en mislukte aflevering.", "tags": [ "Webhook-endpoints" ], "x-klantly-scope": "webhooks.manage", "externalDocs": { "url": "https://developers.klantly.com/nl/reference/webhook-endpoints#webhook-endpointsget" }, "parameters": [ { "name": "endpoint", "in": "path", "required": true, "description": "De id van het webhook-endpoint.", "schema": { "type": "string", "pattern": "^[0-9a-z]{26}$" } } ], "responses": { "200": { "description": "Gelukt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } }, "ETag": { "description": "Versie van het object, voor If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "additionalProperties": false }, "example": { "data": { "object": "webhook_endpoint", "id": "01j7zr8m2k4n6p8r0t2v4w6y8a", "url": "https://example.com/webhooks/klantly", "description": "Boekhouding", "events": [ "customer.created", "deal.won" ], "status": "active", "disabled_reason": null, "disabled_at": null, "previous_secret_expires_at": null, "last_success_at": "2026-09-14T10:15:02Z", "last_failure_at": null, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Deze API-sleutel heeft geen toegang tot deze actie.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Deze API-sleutel heeft geen toegang tot deze actie.", "status": 403, "code": "insufficient_scope", "detail": "Hiervoor is de scope customers.write nodig. Pas de scopes van de sleutel aan in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Niet gevonden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Niet gevonden.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "patch": { "operationId": "webhookEndpointsUpdate", "summary": "Webhook-endpoint bijwerken", "description": "Wijzigt alleen de velden die je meestuurt. Met status zet je het endpoint uit of weer aan; weer aanzetten zet de foutenteller op nul.", "tags": [ "Webhook-endpoints" ], "x-klantly-scope": "webhooks.manage", "externalDocs": { "url": "https://developers.klantly.com/nl/reference/webhook-endpoints#webhook-endpointsupdate" }, "parameters": [ { "name": "endpoint", "in": "path", "required": true, "description": "De id van het webhook-endpoint.", "schema": { "type": "string", "pattern": "^[0-9a-z]{26}$" } }, { "name": "If-Match", "in": "header", "required": false, "description": "De ETag van de versie die je hebt opgehaald. Is het record intussen gewijzigd, dan volgt 412.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointsUpdateRequest" }, "example": { "events": [ "*" ], "status": "active" } } } }, "responses": { "200": { "description": "Gelukt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } }, "ETag": { "description": "Versie van het object, voor If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "additionalProperties": false }, "example": { "data": { "object": "webhook_endpoint", "id": "01j7zr8m2k4n6p8r0t2v4w6y8a", "url": "https://example.com/webhooks/klantly", "description": "Boekhouding", "events": [ "customer.created", "deal.won" ], "status": "active", "disabled_reason": null, "disabled_at": null, "previous_secret_expires_at": null, "last_success_at": "2026-09-14T10:15:02Z", "last_failure_at": null, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Deze API-sleutel heeft geen toegang tot deze actie.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Deze API-sleutel heeft geen toegang tot deze actie.", "status": 403, "code": "insufficient_scope", "detail": "Hiervoor is de scope customers.write nodig. Pas de scopes van de sleutel aan in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Niet gevonden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Niet gevonden.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "412": { "description": "precondition_failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "precondition_failed": { "summary": "Het record is intussen gewijzigd.", "value": { "type": "https://developers.klantly.com/errors/precondition_failed", "title": "Het record is intussen gewijzigd.", "status": 412, "code": "precondition_failed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "413": { "description": "payload_too_large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payload_too_large": { "summary": "De body van het verzoek is te groot.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "De body van het verzoek is te groot.", "status": 413, "code": "payload_too_large", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "415": { "description": "unsupported_media_type", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unsupported_media_type": { "summary": "Dit formaat wordt niet ondersteund.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Dit formaat wordt niet ondersteund.", "status": 415, "code": "unsupported_media_type", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed / unknown_field", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "De invoer is ongeldig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "De invoer is ongeldig.", "status": 422, "code": "validation_failed", "detail": "1 veld is ongeldig.", "errors": { "email": [ "Email moet een geldig e-mailadres zijn." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "De invoer bevat een onbekend veld.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "De invoer bevat een onbekend veld.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "delete": { "operationId": "webhookEndpointsDelete", "summary": "Webhook-endpoint verwijderen", "description": "Verwijdert het endpoint. Events die nog onderweg zijn, worden niet meer afgeleverd.", "tags": [ "Webhook-endpoints" ], "x-klantly-scope": "webhooks.manage", "externalDocs": { "url": "https://developers.klantly.com/nl/reference/webhook-endpoints#webhook-endpointsdelete" }, "parameters": [ { "name": "endpoint", "in": "path", "required": true, "description": "De id van het webhook-endpoint.", "schema": { "type": "string", "pattern": "^[0-9a-z]{26}$" } } ], "responses": { "200": { "description": "Gelukt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } }, "ETag": { "description": "Versie van het object, voor If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DeletedObject" } }, "additionalProperties": false }, "example": { "data": { "object": "note", "id": "9d3f7b41-2d6f-4e8c-9b3a-4f5d6e7a8b92", "deleted": true } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Deze API-sleutel heeft geen toegang tot deze actie.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Deze API-sleutel heeft geen toegang tot deze actie.", "status": 403, "code": "insufficient_scope", "detail": "Hiervoor is de scope customers.write nodig. Pas de scopes van de sleutel aan in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Niet gevonden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Niet gevonden.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/webhook-endpoints/{endpoint}/test": { "post": { "operationId": "webhookEndpointsTest", "summary": "Testbericht versturen", "description": "Stuurt direct het event ping naar het endpoint, ook als het uitstaat, en geeft de afleverpoging terug. Een testbericht wordt niet herhaald.", "tags": [ "Webhook-endpoints" ], "x-klantly-scope": "webhooks.manage", "externalDocs": { "url": "https://developers.klantly.com/nl/reference/webhook-endpoints#webhook-endpointstest" }, "parameters": [ { "name": "endpoint", "in": "path", "required": true, "description": "De id van het webhook-endpoint.", "schema": { "type": "string", "pattern": "^[0-9a-z]{26}$" } } ], "responses": { "200": { "description": "Gelukt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } }, "ETag": { "description": "Versie van het object, voor If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookDelivery" } }, "additionalProperties": false }, "example": { "data": { "object": "webhook_delivery", "id": "1834", "webhook_endpoint_id": "01j7zr8m2k4n6p8r0t2v4w6y8a", "event_id": "evt_01j7zs1a2b3c4d5e6f7g8h9j0k", "event_type": "ping", "attempt": 1, "status": "succeeded", "response_status": 200, "error": null, "duration_ms": 184, "created_at": "2026-09-14T10:15:00Z" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Deze API-sleutel heeft geen toegang tot deze actie.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Deze API-sleutel heeft geen toegang tot deze actie.", "status": 403, "code": "insufficient_scope", "detail": "Hiervoor is de scope customers.write nodig. Pas de scopes van de sleutel aan in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Niet gevonden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Niet gevonden.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/webhook-endpoints/{endpoint}/rotate-secret": { "post": { "operationId": "webhookEndpointsRotateSecret", "summary": "Secret vernieuwen", "description": "Maakt een nieuw secret aan en geeft het eenmalig terug. Tijdens de overlap ondertekent Klantly met het oude én het nieuwe secret, zodat je ontvanger zonder onderbreking kan overstappen.", "tags": [ "Webhook-endpoints" ], "x-klantly-scope": "webhooks.manage", "externalDocs": { "url": "https://developers.klantly.com/nl/reference/webhook-endpoints#webhook-endpointsrotate-secret" }, "parameters": [ { "name": "endpoint", "in": "path", "required": true, "description": "De id van het webhook-endpoint.", "schema": { "type": "string", "pattern": "^[0-9a-z]{26}$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Een unieke sleutel per verzoek (bijvoorbeeld een UUID): een nieuwe poging maakt dan geen dubbel record. 24 uur geldig.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointsRotateSecretRequest" }, "example": { "overlap_hours": 24 } } } }, "responses": { "200": { "description": "Gelukt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } }, "ETag": { "description": "Versie van het object, voor If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpointWithSecret" } }, "additionalProperties": false }, "example": { "data": { "object": "webhook_endpoint", "id": "01j7zr8m2k4n6p8r0t2v4w6y8a", "url": "https://example.com/webhooks/klantly", "description": "Boekhouding", "events": [ "customer.created", "deal.won" ], "status": "active", "disabled_reason": null, "disabled_at": null, "previous_secret_expires_at": null, "last_success_at": "2026-09-14T10:15:02Z", "last_failure_at": null, "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z", "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw" } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Deze API-sleutel heeft geen toegang tot deze actie.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Deze API-sleutel heeft geen toegang tot deze actie.", "status": 403, "code": "insufficient_scope", "detail": "Hiervoor is de scope customers.write nodig. Pas de scopes van de sleutel aan in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Niet gevonden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Niet gevonden.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "409": { "description": "idempotency_in_progress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_in_progress": { "summary": "Een verzoek met deze Idempotency-Key is nog bezig.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Een verzoek met deze Idempotency-Key is nog bezig.", "status": 409, "code": "idempotency_in_progress", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "413": { "description": "payload_too_large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payload_too_large": { "summary": "De body van het verzoek is te groot.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "De body van het verzoek is te groot.", "status": 413, "code": "payload_too_large", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "415": { "description": "unsupported_media_type", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unsupported_media_type": { "summary": "Dit formaat wordt niet ondersteund.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Dit formaat wordt niet ondersteund.", "status": 415, "code": "unsupported_media_type", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed / unknown_field / idempotency_key_reused", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "De invoer is ongeldig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "De invoer is ongeldig.", "status": 422, "code": "validation_failed", "detail": "1 veld is ongeldig.", "errors": { "email": [ "Email moet een geldig e-mailadres zijn." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "De invoer bevat een onbekend veld.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "De invoer bevat een onbekend veld.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_key_reused": { "summary": "Deze Idempotency-Key is al gebruikt voor een ander verzoek.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Deze Idempotency-Key is al gebruikt voor een ander verzoek.", "status": 422, "code": "idempotency_key_reused", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/events": { "get": { "operationId": "eventsList", "summary": "Events opvragen", "description": "De events van de afgelopen 30 dagen, nieuwste eerst. Je ziet alleen events over gegevens waar je sleutel leesrecht op heeft. Met sort=created_at en filter[created_since] haal je gemiste events op volgorde in.", "tags": [ "Events" ], "x-klantly-scope": "events.read", "externalDocs": { "url": "https://developers.klantly.com/nl/reference/events#eventslist" }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Aantal resultaten per pagina.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "De next_cursor of prev_cursor uit meta van het vorige antwoord.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "created_at houdt de volgorde aan waarin alles gebeurde, -created_at (standaard) toont het nieuwste eerst.", "schema": { "type": "string", "enum": [ "-created_at", "created_at" ], "default": "-created_at" } }, { "name": "filter[type]", "in": "query", "required": false, "description": "Alleen deze eventtypes, gescheiden door komma's, bijvoorbeeld customer.created,deal.won.", "schema": { "type": "string", "maxLength": 500 } }, { "name": "filter[created_since]", "in": "query", "required": false, "description": "Alleen events vanaf dit tijdstip: ISO 8601 mét tijdzone, bijvoorbeeld 2026-09-14T10:15:00Z.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Gelukt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "additionalProperties": false }, "example": { "data": [ { "object": "event", "id": "evt_01j7zs1a2b3c4d5e6f7g8h9j0k", "type": "customer.created", "created_at": "2026-09-14T10:15:00Z", "data": { "object": { "object": "customer", "id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "type": "business", "status": "lead", "name": "Jan de Vries", "email": "jan@example.com", "phone": "+31 6 12345678", "company_name": "De Vries Bouw", "vat_number": "NL123456789B01", "coc_number": "12345678", "address": "Dorpsstraat 1", "postal_code": "3511 AB", "city": "Utrecht", "country": "NL", "email_unsubscribed": false, "converted_at": null, "last_activity_at": "2026-09-14T10:15:00Z", "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } ], "meta": { "limit": 50, "next_cursor": "eyJpZCI6IjlkM2Y2YzFlIn0", "prev_cursor": null } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Deze API-sleutel heeft geen toegang tot deze actie.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Deze API-sleutel heeft geen toegang tot deze actie.", "status": 403, "code": "insufficient_scope", "detail": "Hiervoor is de scope customers.write nodig. Pas de scopes van de sleutel aan in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "422": { "description": "validation_failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "De invoer is ongeldig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "De invoer is ongeldig.", "status": 422, "code": "validation_failed", "detail": "1 veld is ongeldig.", "errors": { "email": [ "Email moet een geldig e-mailadres zijn." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/events/{event}": { "get": { "operationId": "eventsGet", "summary": "Event ophalen", "description": "Eén event op id, bijvoorbeeld de webhook-id uit een ontvangen bericht.", "tags": [ "Events" ], "x-klantly-scope": "events.read", "externalDocs": { "url": "https://developers.klantly.com/nl/reference/events#eventsget" }, "parameters": [ { "name": "event", "in": "path", "required": true, "description": "De id van het event (evt_…).", "schema": { "type": "string", "pattern": "^evt_[0-9a-z]{26}$" } } ], "responses": { "200": { "description": "Gelukt", "headers": { "X-Request-Id": { "description": "Unieke id van dit verzoek. Noem hem bij vragen aan support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Resterende verzoeken en seconden tot de reset van de krapste limiet.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle limieten die voor dit verzoek gelden.", "schema": { "type": "string" } }, "ETag": { "description": "Versie van het object, voor If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Event" } }, "additionalProperties": false }, "example": { "data": { "object": "event", "id": "evt_01j7zs1a2b3c4d5e6f7g8h9j0k", "type": "customer.created", "created_at": "2026-09-14T10:15:00Z", "data": { "object": { "object": "customer", "id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "type": "business", "status": "lead", "name": "Jan de Vries", "email": "jan@example.com", "phone": "+31 6 12345678", "company_name": "De Vries Bouw", "vat_number": "NL123456789B01", "coc_number": "12345678", "address": "Dorpsstraat 1", "postal_code": "3511 AB", "city": "Utrecht", "country": "NL", "email_unsubscribed": false, "converted_at": null, "last_activity_at": "2026-09-14T10:15:00Z", "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } } } } } } }, "401": { "description": "unauthenticated / invalid_api_key / api_key_revoked / api_key_expired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Authenticatie vereist.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authenticatie vereist.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ongeldige API-sleutel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ongeldige API-sleutel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Deze API-sleutel is ingetrokken.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Deze API-sleutel is ingetrokken.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Deze API-sleutel is verlopen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Deze API-sleutel is verlopen.", "status": 401, "code": "api_key_expired", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "403": { "description": "insufficient_scope / ip_not_allowed / account_suspended / subscription_inactive / feature_not_available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "summary": "Deze API-sleutel heeft geen toegang tot deze actie.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Deze API-sleutel heeft geen toegang tot deze actie.", "status": 403, "code": "insufficient_scope", "detail": "Hiervoor is de scope customers.write nodig. Pas de scopes van de sleutel aan in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Dit IP-adres mag deze API-sleutel niet gebruiken.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Het account van dit bedrijf is geblokkeerd.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Het account van dit bedrijf is geblokkeerd.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dit bedrijf heeft geen actief abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dit bedrijf heeft geen actief abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Deze functie is niet beschikbaar voor dit bedrijf.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Deze functie is niet beschikbaar voor dit bedrijf.", "status": 403, "code": "feature_not_available", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Niet gevonden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Niet gevonden.", "status": 404, "code": "not_found", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Te veel verzoeken.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Te veel verzoeken.", "status": 429, "code": "rate_limited", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "500": { "description": "server_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "server_error": { "summary": "Er ging iets mis aan onze kant.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Er ging iets mis aan onze kant.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API-sleutel van je bedrijf (kly_…), aan te maken in Klantly onder Integraties → API." } }, "schemas": { "Problem": { "type": "object", "description": "Een fout volgens RFC 9457 (problem details).", "required": [ "type", "title", "status", "code" ], "properties": { "type": { "type": "string", "format": "uri", "description": "URL van de uitlegpagina van deze fout." }, "title": { "type": "string", "description": "Korte omschrijving, in de taal van het verzoek." }, "status": { "type": "integer", "description": "HTTP-statuscode." }, "code": { "type": "string", "enum": [ "bad_request", "unauthenticated", "invalid_api_key", "api_key_revoked", "api_key_expired", "ip_not_allowed", "account_suspended", "subscription_inactive", "feature_not_available", "insufficient_scope", "forbidden", "limit_reached", "not_found", "method_not_allowed", "conflict", "invalid_state_transition", "idempotency_in_progress", "precondition_failed", "payload_too_large", "unsupported_media_type", "validation_failed", "unknown_field", "idempotency_key_reused", "rate_limited", "server_error", "api_disabled" ], "description": "Vaste, Engelse foutcode: programmeer hierop." }, "detail": { "type": "string", "description": "Uitleg bij deze specifieke fout." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Validatiefouten per veld." }, "request_id": { "type": "string", "description": "Id van het verzoek, voor support." } } }, "ListMeta": { "type": "object", "required": [ "limit", "next_cursor", "prev_cursor" ], "properties": { "limit": { "type": "integer", "description": "Aantal resultaten per pagina.", "examples": [ 50 ] }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor voor de volgende pagina, of null op de laatste pagina.", "examples": [ "eyJpZCI6IjlkM2Y2YzFlIn0" ] }, "prev_cursor": { "type": [ "string", "null" ], "description": "Cursor voor de vorige pagina, of null op de eerste pagina.", "examples": [ null ] } }, "additionalProperties": false }, "Customer": { "type": "object", "required": [ "object", "id", "type", "status", "name", "email", "phone", "company_name", "vat_number", "coc_number", "address", "postal_code", "city", "country", "email_unsubscribed", "converted_at", "last_activity_at", "created_at", "updated_at" ], "properties": { "object": { "type": "string", "const": "customer", "description": "Altijd \"customer\".", "examples": [ "customer" ] }, "id": { "type": "string", "format": "uuid", "description": "Unieke id (UUID).", "examples": [ "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" ] }, "type": { "type": "string", "enum": [ "individual", "business" ], "description": "individual (particulier) of business (bedrijf).", "examples": [ "business" ] }, "status": { "type": "string", "enum": [ "lead", "customer" ], "description": "lead of customer (klant).", "examples": [ "lead" ] }, "name": { "type": [ "string", "null" ], "description": "Naam van de contactpersoon.", "examples": [ "Jan de Vries" ] }, "email": { "type": "string", "format": "email", "description": "E-mailadres; uniek binnen je bedrijf.", "examples": [ "jan@example.com" ] }, "phone": { "type": [ "string", "null" ], "description": "Telefoonnummer.", "examples": [ "+31 6 12345678" ] }, "company_name": { "type": [ "string", "null" ], "description": "Bedrijfsnaam, bij een zakelijke klant.", "examples": [ "De Vries Bouw" ] }, "vat_number": { "type": [ "string", "null" ], "description": "Btw-nummer.", "examples": [ "NL123456789B01" ] }, "coc_number": { "type": [ "string", "null" ], "description": "KvK-nummer.", "examples": [ "12345678" ] }, "address": { "type": [ "string", "null" ], "description": "Straat en huisnummer.", "examples": [ "Dorpsstraat 1" ] }, "postal_code": { "type": [ "string", "null" ], "description": "Postcode.", "examples": [ "3511 AB" ] }, "city": { "type": [ "string", "null" ], "description": "Plaats.", "examples": [ "Utrecht" ] }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Land.", "examples": [ "NL" ] }, "email_unsubscribed": { "type": "boolean", "description": "Heeft zich afgemeld voor e-mail.", "examples": [ false ] }, "converted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Wanneer de lead klant werd.", "examples": [ null ] }, "last_activity_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Laatste activiteit in Klantly.", "examples": [ "2026-09-14T10:15:00Z" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Aangemaakt op (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Laatst gewijzigd op (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] } }, "additionalProperties": false }, "ApiKey": { "type": "object", "required": [ "object", "id", "name", "prefix", "scopes", "expires_at", "created_at", "company", "rate_limits" ], "properties": { "object": { "type": "string", "const": "api_key", "description": "Altijd \"api_key\".", "examples": [ "api_key" ] }, "id": { "type": "string", "description": "Id van de sleutel.", "examples": [ "01j7zq3k9x2m4n6p8r0t2v4w6y" ] }, "name": { "type": "string", "description": "De naam die de sleutel in Klantly kreeg.", "examples": [ "Website" ] }, "prefix": { "type": "string", "description": "Het begin van de sleutel, om hem te herkennen.", "examples": [ "kly_4fZ2mQ8v" ] }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "De scopes van de sleutel.", "examples": [ [ "customers.read", "customers.write" ] ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Vervaldatum, of null als de sleutel niet verloopt.", "examples": [ "2027-09-14T10:15:00Z" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Aangemaakt op (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "company": { "description": "Het bedrijf waar de sleutel bij hoort.", "type": "object", "required": [ "object", "id", "name" ], "properties": { "object": { "type": "string", "const": "company", "description": "Altijd \"company\".", "examples": [ "company" ] }, "id": { "type": "string", "description": "Id van het bedrijf.", "examples": [ "42" ] }, "name": { "type": "string", "description": "Naam van het bedrijf.", "examples": [ "De Vries Bouw" ] } }, "additionalProperties": false }, "rate_limits": { "type": "array", "items": { "type": "object", "required": [ "name", "limit", "window_seconds" ], "properties": { "name": { "type": "string", "description": "Naam van de limiet.", "examples": [ "key_minute" ] }, "limit": { "type": "integer", "description": "Maximaal aantal verzoeken in het venster.", "examples": [ 120 ] }, "window_seconds": { "type": "integer", "description": "Lengte van het venster in seconden.", "examples": [ 60 ] } }, "additionalProperties": false }, "description": "De limieten die voor deze sleutel gelden.", "examples": [ [ { "name": "key_minute", "limit": 120, "window_seconds": 60 } ] ] } }, "additionalProperties": false }, "Company": { "type": "object", "required": [ "object", "id", "name", "email", "phone", "website", "coc_number", "vat_number", "address", "postal_code", "city", "country", "language", "currency", "timezone", "default_vat_rate", "prices_include_vat" ], "properties": { "object": { "type": "string", "const": "company", "description": "Altijd \"company\".", "examples": [ "company" ] }, "id": { "type": "string", "description": "Id van het bedrijf.", "examples": [ "42" ] }, "name": { "type": "string", "description": "Bedrijfsnaam.", "examples": [ "De Vries Bouw" ] }, "email": { "type": [ "string", "null" ], "description": "Algemeen e-mailadres.", "examples": [ "info@devriesbouw.nl" ] }, "phone": { "type": [ "string", "null" ], "description": "Telefoonnummer.", "examples": [ "+31 30 1234567" ] }, "website": { "type": [ "string", "null" ], "description": "Website.", "examples": [ "https://devriesbouw.nl" ] }, "coc_number": { "type": [ "string", "null" ], "description": "KvK-nummer.", "examples": [ "12345678" ] }, "vat_number": { "type": [ "string", "null" ], "description": "Btw-nummer.", "examples": [ "NL123456789B01" ] }, "address": { "type": [ "string", "null" ], "description": "Straat en huisnummer.", "examples": [ "Industrieweg 5" ] }, "postal_code": { "type": [ "string", "null" ], "description": "Postcode.", "examples": [ "3542 AD" ] }, "city": { "type": [ "string", "null" ], "description": "Plaats.", "examples": [ "Utrecht" ] }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Land, als ISO-code van twee letters (bijvoorbeeld NL).", "examples": [ "NL" ] }, "language": { "type": "string", "enum": [ "nl", "en", "de", "fr" ], "description": "Hoofdtaal van het bedrijf.", "examples": [ "nl" ] }, "currency": { "type": "string", "const": "EUR", "description": "Altijd \"EUR\".", "examples": [ "EUR" ] }, "timezone": { "type": "string", "description": "Tijdzone waarin Klantly tijden aan het bedrijf toont. De API geeft tijden altijd in UTC.", "examples": [ "Europe/Amsterdam" ] }, "default_vat_rate": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "description": "Standaard-btw-percentage, als tekst met twee decimalen.", "examples": [ "21.00" ] }, "prices_include_vat": { "type": "boolean", "description": "Of prijzen standaard inclusief btw worden ingevoerd.", "examples": [ false ] } }, "additionalProperties": false }, "User": { "type": "object", "required": [ "object", "id", "name", "email", "role", "is_owner", "status", "created_at" ], "properties": { "object": { "type": "string", "const": "user", "description": "Altijd \"user\".", "examples": [ "user" ] }, "id": { "type": "string", "description": "Id van de gebruiker.", "examples": [ "7" ] }, "name": { "type": "string", "description": "Naam.", "examples": [ "Sanne Bakker" ] }, "email": { "type": "string", "format": "email", "description": "E-mailadres.", "examples": [ "sanne@devriesbouw.nl" ] }, "role": { "type": [ "string", "null" ], "description": "Naam van de rol in je bedrijf, of null zonder rol.", "examples": [ "Verkoop" ] }, "is_owner": { "type": "boolean", "description": "De eigenaar van het account.", "examples": [ false ] }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "active of inactive (gedeactiveerd).", "examples": [ "active" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Aangemaakt op (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] } }, "additionalProperties": false }, "CustomerActivity": { "type": "object", "required": [ "object", "id", "customer_id", "type", "title", "description", "related", "happened_at", "created_at" ], "properties": { "object": { "type": "string", "const": "customer_activity", "description": "Altijd \"customer_activity\".", "examples": [ "customer_activity" ] }, "id": { "type": "string", "format": "uuid", "description": "Unieke id (UUID).", "examples": [ "9d3f7c62-3e7a-4f9d-8c4b-5a6e7f8a9ba3" ] }, "customer_id": { "type": "string", "format": "uuid", "description": "De klant waar de activiteit bij hoort.", "examples": [ "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" ] }, "type": { "type": "string", "description": "Soort activiteit, bijvoorbeeld quote_sent, invoice_created of appointment_created. Er kunnen soorten bijkomen: vang een onbekende waarde netjes op.", "examples": [ "quote_sent" ] }, "title": { "type": [ "string", "null" ], "description": "Korte omschrijving.", "examples": [ null ] }, "description": { "type": [ "string", "null" ], "description": "Toelichting.", "examples": [ null ] }, "related": { "description": "Verwijzingen naar gekoppelde records; alleen de verwijzingen die van toepassing zijn, hebben een waarde.", "type": "object", "required": [ "quote_id", "invoice_id", "appointment_id", "work_order_id", "task_id", "deal_id", "order_id", "conversation_id" ], "properties": { "quote_id": { "type": [ "string", "null" ], "description": "Id van de gekoppelde offerte.", "examples": [ null ] }, "invoice_id": { "type": [ "string", "null" ], "description": "Id van de gekoppelde factuur.", "examples": [ null ] }, "appointment_id": { "type": [ "string", "null" ], "description": "Id van de gekoppelde afspraak.", "examples": [ null ] }, "work_order_id": { "type": [ "string", "null" ], "description": "Id van de gekoppelde werkbon.", "examples": [ null ] }, "task_id": { "type": [ "string", "null" ], "description": "Id van de gekoppelde taak.", "examples": [ null ] }, "deal_id": { "type": [ "string", "null" ], "description": "Id van de gekoppelde deal.", "examples": [ null ] }, "order_id": { "type": [ "string", "null" ], "description": "Id van de gekoppelde bestelling.", "examples": [ null ] }, "conversation_id": { "type": [ "string", "null" ], "description": "Id van het gekoppelde gesprek.", "examples": [ null ] } }, "additionalProperties": false }, "happened_at": { "type": "string", "format": "date-time", "description": "Wanneer het gebeurde (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Vastgelegd op (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] } }, "additionalProperties": false }, "Note": { "type": "object", "required": [ "object", "id", "content", "is_important", "parent", "author", "created_at", "updated_at" ], "properties": { "object": { "type": "string", "const": "note", "description": "Altijd \"note\".", "examples": [ "note" ] }, "id": { "type": "string", "format": "uuid", "description": "Unieke id (UUID).", "examples": [ "9d3f7b41-2d6f-4e8c-9b3a-4f5d6e7a8b92" ] }, "content": { "type": "string", "description": "De tekst van de notitie.", "examples": [ "Klant belt terug na de vakantie." ] }, "is_important": { "type": "boolean", "description": "Gemarkeerd als belangrijk.", "examples": [ true ] }, "parent": { "description": "Waar de notitie bij hoort.", "type": "object", "required": [ "object", "id" ], "properties": { "object": { "type": "string", "enum": [ "customer", "deal" ], "description": "\"customer\" of \"deal\".", "examples": [ "customer" ] }, "id": { "type": "string", "format": "uuid", "description": "Id van de klant of deal.", "examples": [ "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" ] } }, "additionalProperties": false }, "author": { "description": "Wie de notitie schreef, of null bij een notitie via de API.", "type": [ "object", "null" ], "required": [ "object", "id", "name" ], "properties": { "object": { "type": "string", "const": "user", "description": "Altijd \"user\".", "examples": [ "user" ] }, "id": { "type": "string", "description": "Id van de gebruiker.", "examples": [ "7" ] }, "name": { "type": "string", "description": "Naam van de gebruiker.", "examples": [ "Sanne Bakker" ] } }, "additionalProperties": false }, "created_at": { "type": "string", "format": "date-time", "description": "Aangemaakt op (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Laatst gewijzigd op (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] } }, "additionalProperties": false }, "PipelineStage": { "type": "object", "required": [ "object", "id", "name", "names", "type", "is_default", "position", "probability", "color" ], "properties": { "object": { "type": "string", "const": "pipeline_stage", "description": "Altijd \"pipeline_stage\".", "examples": [ "pipeline_stage" ] }, "id": { "type": "string", "description": "Id van de fase.", "examples": [ "3" ] }, "name": { "type": "string", "description": "Naam in de taal van het verzoek.", "examples": [ "Offerte verstuurd" ] }, "names": { "description": "De naam in alle vier de talen.", "type": "object", "required": [ "nl", "en", "de", "fr" ], "properties": { "nl": { "type": [ "string", "null" ], "description": "Nederlandse naam.", "examples": [ "Offerte verstuurd" ] }, "en": { "type": [ "string", "null" ], "description": "Engelse naam.", "examples": [ "Quote sent" ] }, "de": { "type": [ "string", "null" ], "description": "Duitse naam.", "examples": [ "Angebot gesendet" ] }, "fr": { "type": [ "string", "null" ], "description": "Franse naam.", "examples": [ "Devis envoyé" ] } }, "additionalProperties": false }, "type": { "type": "string", "enum": [ "open", "won", "lost" ], "description": "open, won (gewonnen) of lost (verloren): een deal in deze fase krijgt die status.", "examples": [ "open" ] }, "is_default": { "type": "boolean", "description": "Nieuwe deals komen in deze fase terecht.", "examples": [ false ] }, "position": { "type": "integer", "description": "Plaats op het bord, van links naar rechts.", "examples": [ 3 ] }, "probability": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "description": "Kans op winnen in procenten, als tekst met twee decimalen.", "examples": [ "50.00" ] }, "color": { "type": [ "string", "null" ], "description": "Kleur op het bord (hex).", "examples": [ "#3B82F6" ] } }, "additionalProperties": false }, "Deal": { "type": "object", "required": [ "object", "id", "title", "description", "status", "value", "currency", "value_source", "stage", "customer_id", "assigned_user_id", "source", "lost_reason", "is_archived", "stage_changed_at", "won_at", "lost_at", "archived_at", "created_at", "updated_at" ], "properties": { "object": { "type": "string", "const": "deal", "description": "Altijd \"deal\".", "examples": [ "deal" ] }, "id": { "type": "string", "format": "uuid", "description": "Unieke id (UUID).", "examples": [ "9d3f7a20-1c5e-4d7b-8a2f-3e4c5d6f7a81" ] }, "title": { "type": "string", "description": "Titel van de deal.", "examples": [ "Veranda 5x3 m" ] }, "description": { "type": [ "string", "null" ], "description": "Omschrijving.", "examples": [ null ] }, "status": { "type": "string", "enum": [ "open", "won", "lost" ], "description": "open, won (gewonnen) of lost (verloren); volgt uit de fase.", "examples": [ "open" ] }, "value": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "description": "Waarde als tekst met twee decimalen, bijvoorbeeld \"8450.00\". Bij aanmaken en bijwerken mag je ook een getal sturen.", "examples": [ "8450.00" ] }, "currency": { "type": "string", "const": "EUR", "description": "Altijd \"EUR\".", "examples": [ "EUR" ] }, "value_source": { "type": "string", "enum": [ "quotes", "manual" ], "description": "quotes: de waarde volgt uit de gekoppelde offertes; manual: met de hand ingesteld.", "examples": [ "manual" ] }, "stage": { "description": "De fase waar de deal in staat; de namen staan in Pipelinefasen opvragen.", "type": [ "object", "null" ], "required": [ "object", "id" ], "properties": { "object": { "type": "string", "const": "pipeline_stage", "description": "Altijd \"pipeline_stage\".", "examples": [ "pipeline_stage" ] }, "id": { "type": "string", "description": "Id van de fase.", "examples": [ "3" ] } }, "additionalProperties": false }, "customer_id": { "type": [ "string", "null" ], "format": "uuid", "description": "De klant van de deal.", "examples": [ "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" ] }, "assigned_user_id": { "type": [ "string", "null" ], "description": "De gebruiker die de deal behandelt, of null.", "examples": [ "7" ] }, "source": { "type": [ "string", "null" ], "description": "Waar de deal vandaan komt; via de API is dat api.", "examples": [ "api" ] }, "lost_reason": { "type": [ "string", "null" ], "description": "Waarom de deal verloren is, of null.", "examples": [ null ] }, "is_archived": { "type": "boolean", "description": "Gearchiveerd: staat niet meer op het bord.", "examples": [ false ] }, "stage_changed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Wanneer de deal voor het laatst van fase wisselde.", "examples": [ "2026-09-14T10:15:00Z" ] }, "won_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Wanneer de deal gewonnen werd.", "examples": [ null ] }, "lost_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Wanneer de deal verloren werd.", "examples": [ null ] }, "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Wanneer de deal gearchiveerd werd.", "examples": [ null ] }, "created_at": { "type": "string", "format": "date-time", "description": "Aangemaakt op (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Laatst gewijzigd op (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] } }, "additionalProperties": false }, "DealAction": { "type": "object", "required": [ "stage_id", "notes" ], "properties": { "stage_id": { "type": "integer", "description": "De id van de fase waar de deal naartoe gaat (uit Pipelinefasen opvragen).", "examples": [ 3 ] }, "notes": { "type": [ "string", "null" ], "description": "Optionele toelichting; wordt met de fasewissel in de geschiedenis van de deal bewaard.", "examples": [ null ] } }, "additionalProperties": false }, "WebhookEndpoint": { "type": "object", "required": [ "object", "id", "url", "description", "events", "status", "disabled_reason", "disabled_at", "previous_secret_expires_at", "last_success_at", "last_failure_at", "created_at", "updated_at" ], "properties": { "object": { "type": "string", "const": "webhook_endpoint", "description": "Altijd \"webhook_endpoint\".", "examples": [ "webhook_endpoint" ] }, "id": { "type": "string", "description": "Id van het endpoint.", "examples": [ "01j7zr8m2k4n6p8r0t2v4w6y8a" ] }, "url": { "type": "string", "format": "uri", "description": "Het https-adres waar Klantly de events naartoe stuurt. Geen interne adressen, en alleen poort 443, 80 of 8443.", "examples": [ "https://example.com/webhooks/klantly" ] }, "description": { "type": [ "string", "null" ], "description": "Eigen omschrijving, bijvoorbeeld waar het endpoint voor dient.", "examples": [ "Boekhouding" ] }, "events": { "type": "array", "items": { "type": "string" }, "description": "De eventtypes die dit endpoint ontvangt, of [\"*\"] voor alle events waar de sleutel of gebruiker leesrecht op heeft.", "examples": [ [ "customer.created", "deal.won" ] ] }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "active of disabled (uitgeschakeld).", "examples": [ "active" ] }, "disabled_reason": { "type": [ "string", "null" ], "enum": [ "failing", "manual", null, null ], "description": "Waarom het endpoint uitstaat: failing (5 dagen alleen fouten) of manual (handmatig), anders null.", "examples": [ null ] }, "disabled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Wanneer het endpoint werd uitgeschakeld.", "examples": [ null ] }, "previous_secret_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Tot wanneer na een vernieuwing ook het vorige secret nog wordt gebruikt, anders null.", "examples": [ null ] }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Laatste geslaagde aflevering.", "examples": [ "2026-09-14T10:15:02Z" ] }, "last_failure_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Laatste mislukte aflevering.", "examples": [ null ] }, "created_at": { "type": "string", "format": "date-time", "description": "Aangemaakt op (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Laatst gewijzigd op (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] } }, "additionalProperties": false }, "WebhookEndpointWithSecret": { "type": "object", "required": [ "object", "id", "url", "description", "events", "status", "disabled_reason", "disabled_at", "previous_secret_expires_at", "last_success_at", "last_failure_at", "created_at", "updated_at", "secret" ], "properties": { "object": { "type": "string", "const": "webhook_endpoint", "description": "Altijd \"webhook_endpoint\".", "examples": [ "webhook_endpoint" ] }, "id": { "type": "string", "description": "Id van het endpoint.", "examples": [ "01j7zr8m2k4n6p8r0t2v4w6y8a" ] }, "url": { "type": "string", "format": "uri", "description": "Het https-adres waar Klantly de events naartoe stuurt. Geen interne adressen, en alleen poort 443, 80 of 8443.", "examples": [ "https://example.com/webhooks/klantly" ] }, "description": { "type": [ "string", "null" ], "description": "Eigen omschrijving, bijvoorbeeld waar het endpoint voor dient.", "examples": [ "Boekhouding" ] }, "events": { "type": "array", "items": { "type": "string" }, "description": "De eventtypes die dit endpoint ontvangt, of [\"*\"] voor alle events waar de sleutel of gebruiker leesrecht op heeft.", "examples": [ [ "customer.created", "deal.won" ] ] }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "active of disabled (uitgeschakeld).", "examples": [ "active" ] }, "disabled_reason": { "type": [ "string", "null" ], "enum": [ "failing", "manual", null, null ], "description": "Waarom het endpoint uitstaat: failing (5 dagen alleen fouten) of manual (handmatig), anders null.", "examples": [ null ] }, "disabled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Wanneer het endpoint werd uitgeschakeld.", "examples": [ null ] }, "previous_secret_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Tot wanneer na een vernieuwing ook het vorige secret nog wordt gebruikt, anders null.", "examples": [ null ] }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Laatste geslaagde aflevering.", "examples": [ "2026-09-14T10:15:02Z" ] }, "last_failure_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Laatste mislukte aflevering.", "examples": [ null ] }, "created_at": { "type": "string", "format": "date-time", "description": "Aangemaakt op (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Laatst gewijzigd op (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "secret": { "type": "string", "pattern": "^whsec_", "description": "Het secret (whsec_…) om handtekeningen te controleren. Alleen in dit antwoord: bewaar het direct.", "examples": [ "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw" ] } }, "additionalProperties": false }, "WebhookDelivery": { "type": "object", "required": [ "object", "id", "webhook_endpoint_id", "event_id", "event_type", "attempt", "status", "response_status", "error", "duration_ms", "created_at" ], "properties": { "object": { "type": "string", "const": "webhook_delivery", "description": "Altijd \"webhook_delivery\".", "examples": [ "webhook_delivery" ] }, "id": { "type": "string", "description": "Id van de afleverpoging.", "examples": [ "1834" ] }, "webhook_endpoint_id": { "type": "string", "description": "Het endpoint.", "examples": [ "01j7zr8m2k4n6p8r0t2v4w6y8a" ] }, "event_id": { "type": "string", "description": "Het event dat werd verstuurd.", "examples": [ "evt_01j7zs1a2b3c4d5e6f7g8h9j0k" ] }, "event_type": { "type": "string", "description": "Het type van het event; ping bij een test.", "examples": [ "ping" ] }, "attempt": { "type": "integer", "description": "Nummer van de poging (1 is de eerste).", "examples": [ 1 ] }, "status": { "type": "string", "enum": [ "succeeded", "failed" ], "description": "succeeded (2xx-antwoord) of failed.", "examples": [ "succeeded" ] }, "response_status": { "type": [ "integer", "null" ], "description": "HTTP-status van je server, of null als er geen antwoord kwam.", "examples": [ 200 ] }, "error": { "type": [ "string", "null" ], "description": "Wat er misging als er geen antwoord kwam, bijvoorbeeld connection_failed, anders null.", "examples": [ null ] }, "duration_ms": { "type": "integer", "description": "Hoe lang de poging duurde, in milliseconden.", "examples": [ 184 ] }, "created_at": { "type": "string", "format": "date-time", "description": "Tijdstip van de poging (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] } }, "additionalProperties": false }, "Event": { "type": "object", "required": [ "object", "id", "type", "created_at", "data" ], "properties": { "object": { "type": "string", "const": "event", "description": "Altijd \"event\".", "examples": [ "event" ] }, "id": { "type": "string", "pattern": "^evt_", "description": "Unieke id (evt_…). Gelijk aan de header webhook-id: gebruik hem om dubbele berichten te herkennen.", "examples": [ "evt_01j7zs1a2b3c4d5e6f7g8h9j0k" ] }, "type": { "type": "string", "enum": [ "customer.created", "customer.updated", "customer.converted", "deal.created", "deal.updated", "deal.stage_changed", "deal.won", "deal.lost", "note.created", "note.updated", "note.deleted" ], "description": "Het soort event, bijvoorbeeld customer.created.", "examples": [ "customer.created" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Wanneer het gebeurde (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "data": { "description": "De inhoud van het event.", "type": "object", "required": [ "object" ], "properties": { "object": { "type": "object", "description": "Het object zoals het na de wijziging was, in dezelfde vorm als in de REST-API (bij note.deleted: zoals het vóór het verwijderen was).", "examples": [ { "object": "customer", "id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70", "type": "business", "status": "lead", "name": "Jan de Vries", "email": "jan@example.com", "phone": "+31 6 12345678", "company_name": "De Vries Bouw", "vat_number": "NL123456789B01", "coc_number": "12345678", "address": "Dorpsstraat 1", "postal_code": "3511 AB", "city": "Utrecht", "country": "NL", "email_unsubscribed": false, "converted_at": null, "last_activity_at": "2026-09-14T10:15:00Z", "created_at": "2026-09-14T10:15:00Z", "updated_at": "2026-09-14T10:15:00Z" } ] } }, "additionalProperties": false } }, "additionalProperties": false }, "DeletedObject": { "type": "object", "required": [ "object", "id", "deleted" ], "properties": { "object": { "type": "string", "enum": [ "note", "webhook_endpoint" ], "description": "Het soort object dat is verwijderd, bijvoorbeeld \"note\".", "examples": [ "note" ] }, "id": { "type": "string", "description": "Id van het verwijderde object.", "examples": [ "9d3f7b41-2d6f-4e8c-9b3a-4f5d6e7a8b92" ] }, "deleted": { "type": "boolean", "const": true, "description": "Altijd true.", "examples": [ true ] } }, "additionalProperties": false }, "CustomersCreateRequest": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 255, "x-unique": true, "description": "E-mailadres; uniek binnen je bedrijf." }, "type": { "type": "string", "enum": [ "individual", "business" ], "description": "individual (particulier) of business (bedrijf)." }, "name": { "type": [ "string", "null" ], "maxLength": 255, "description": "Naam van de contactpersoon." }, "phone": { "type": [ "string", "null" ], "maxLength": 255, "description": "Telefoonnummer." }, "address": { "type": [ "string", "null" ], "maxLength": 255, "description": "Straat en huisnummer." }, "city": { "type": [ "string", "null" ], "maxLength": 255, "description": "Plaats." }, "postal_code": { "type": [ "string", "null" ], "maxLength": 64, "description": "Postcode." }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "minLength": 2, "maxLength": 2, "description": "Land." }, "company_name": { "type": [ "string", "null" ], "maxLength": 255, "description": "Bedrijfsnaam, bij een zakelijke klant." }, "vat_number": { "type": [ "string", "null" ], "maxLength": 20, "description": "Btw-nummer." }, "coc_number": { "type": [ "string", "null" ], "maxLength": 30, "description": "KvK-nummer." } }, "additionalProperties": false }, "CustomersUpdateRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 255, "x-unique": true, "description": "E-mailadres; uniek binnen je bedrijf." }, "type": { "type": "string", "enum": [ "individual", "business" ], "description": "individual (particulier) of business (bedrijf)." }, "name": { "type": [ "string", "null" ], "maxLength": 255, "description": "Naam van de contactpersoon." }, "phone": { "type": [ "string", "null" ], "maxLength": 255, "description": "Telefoonnummer." }, "address": { "type": [ "string", "null" ], "maxLength": 255, "description": "Straat en huisnummer." }, "city": { "type": [ "string", "null" ], "maxLength": 255, "description": "Plaats." }, "postal_code": { "type": [ "string", "null" ], "maxLength": 64, "description": "Postcode." }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "minLength": 2, "maxLength": 2, "description": "Land." }, "company_name": { "type": [ "string", "null" ], "maxLength": 255, "description": "Bedrijfsnaam, bij een zakelijke klant." }, "vat_number": { "type": [ "string", "null" ], "maxLength": 20, "description": "Btw-nummer." }, "coc_number": { "type": [ "string", "null" ], "maxLength": 30, "description": "KvK-nummer." } }, "additionalProperties": false }, "NotesCreateCustomerRequest": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "maxLength": 10000, "description": "De tekst van de notitie." }, "is_important": { "type": "boolean", "description": "Gemarkeerd als belangrijk." } }, "additionalProperties": false }, "NotesUpdateCustomerRequest": { "type": "object", "properties": { "content": { "type": "string", "maxLength": 10000, "description": "De tekst van de notitie." }, "is_important": { "type": "boolean", "description": "Gemarkeerd als belangrijk." } }, "additionalProperties": false }, "NotesCreateDealRequest": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "maxLength": 10000, "description": "De tekst van de notitie." }, "is_important": { "type": "boolean", "description": "Gemarkeerd als belangrijk." } }, "additionalProperties": false }, "NotesUpdateDealRequest": { "type": "object", "properties": { "content": { "type": "string", "maxLength": 10000, "description": "De tekst van de notitie." }, "is_important": { "type": "boolean", "description": "Gemarkeerd als belangrijk." } }, "additionalProperties": false }, "DealsCreateRequest": { "type": "object", "required": [ "customer_id" ], "properties": { "customer_id": { "type": "string", "format": "uuid", "description": "De klant van de deal." }, "title": { "type": [ "string", "null" ], "maxLength": 255, "description": "Titel van de deal." }, "description": { "type": [ "string", "null" ], "maxLength": 10000, "description": "Omschrijving." }, "value": { "type": [ "number", "null" ], "minimum": 0, "maximum": 99999999, "multipleOf": 0.01, "description": "Waarde als tekst met twee decimalen, bijvoorbeeld \"8450.00\". Bij aanmaken en bijwerken mag je ook een getal sturen." }, "stage_id": { "type": [ "integer", "null" ], "description": "De fase waar de deal in komt. Zonder stage_id: de standaardfase." }, "assigned_user_id": { "type": [ "integer", "null" ], "description": "De gebruiker die de deal behandelt, of null." } }, "additionalProperties": false }, "DealsUpdateRequest": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 255, "description": "Titel van de deal." }, "description": { "type": [ "string", "null" ], "maxLength": 10000, "description": "Omschrijving." }, "value": { "type": "number", "minimum": 0, "maximum": 99999999, "multipleOf": 0.01, "description": "Waarde als tekst met twee decimalen, bijvoorbeeld \"8450.00\". Bij aanmaken en bijwerken mag je ook een getal sturen." }, "assigned_user_id": { "type": [ "integer", "null" ], "description": "De gebruiker die de deal behandelt, of null." } }, "additionalProperties": false }, "DealsMoveRequest": { "type": "object", "required": [ "stage_id" ], "properties": { "stage_id": { "type": "integer", "description": "De id van de fase waar de deal naartoe gaat (uit Pipelinefasen opvragen)." }, "notes": { "type": [ "string", "null" ], "maxLength": 500, "description": "Optionele toelichting; wordt met de fasewissel in de geschiedenis van de deal bewaard." } }, "additionalProperties": false }, "DealsLoseRequest": { "type": "object", "properties": { "lost_reason": { "type": [ "string", "null" ], "maxLength": 255, "description": "Waarom de deal verloren is, of null." } }, "additionalProperties": false }, "WebhookEndpointsCreateRequest": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Het https-adres waar Klantly de events naartoe stuurt. Geen interne adressen, en alleen poort 443, 80 of 8443." }, "description": { "type": [ "string", "null" ], "maxLength": 255, "description": "Eigen omschrijving, bijvoorbeeld waar het endpoint voor dient." }, "events": { "type": "array", "minItems": 1, "maxItems": 50, "description": "De eventtypes die dit endpoint ontvangt, of [\"*\"] voor alle events waar de sleutel of gebruiker leesrecht op heeft." } }, "additionalProperties": false }, "WebhookEndpointsUpdateRequest": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Het https-adres waar Klantly de events naartoe stuurt. Geen interne adressen, en alleen poort 443, 80 of 8443." }, "description": { "type": [ "string", "null" ], "maxLength": 255, "description": "Eigen omschrijving, bijvoorbeeld waar het endpoint voor dient." }, "events": { "type": "array", "minItems": 1, "maxItems": 50, "description": "De eventtypes die dit endpoint ontvangt, of [\"*\"] voor alle events waar de sleutel of gebruiker leesrecht op heeft." }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "active of disabled (uitgeschakeld)." } }, "additionalProperties": false }, "WebhookEndpointsRotateSecretRequest": { "type": "object", "properties": { "overlap_hours": { "type": "integer", "enum": [ "0", "1", "24", "168" ], "description": "Hoe lang het oude secret naast het nieuwe blijft werken: 0, 1, 24 (standaard) of 168 uur." } }, "additionalProperties": false } } } }