{ "openapi": "3.1.0", "info": { "title": "Klantly API", "version": "1.0.0", "description": "The public API of Klantly. Authenticate with an API key as a Bearer token. Guides, error codes and examples are on the developer portal.", "contact": { "name": "Klantly", "url": "https://developers.klantly.com/en/support" } }, "externalDocs": { "url": "https://developers.klantly.com/en", "description": "Klantly Developers" }, "servers": [ { "url": "https://app.klantly.com/api/v1" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "API key", "description": "Test your connection and see which key, company, scopes and limits apply." }, { "name": "Company", "description": "Your own company details: name, address, language and VAT settings." }, { "name": "Users", "description": "The users of your company, for example to assign a deal to someone." }, { "name": "Customers", "description": "Customers and leads: create, look up, update and convert a lead into a customer." }, { "name": "Notes", "description": "Internal notes on a customer or a deal. Your customer never sees them." }, { "name": "Pipeline stages", "description": "The stages of your pipeline board, in order, and whether a stage means open, won or lost." }, { "name": "Deals", "description": "The cards on your pipeline board: create, update, move to another stage, win, lose and archive." }, { "name": "Webhook endpoints", "description": "URLs Klantly sends a message to as soon as something changes. Signing and retries are explained in the webhooks guide." }, { "name": "Events", "description": "Everything that changed in the last 30 days, as a list. To catch up on missed webhooks, or to poll instead of using webhooks." } ], "paths": { "/me": { "get": { "operationId": "me", "summary": "Retrieve key and company", "description": "Returns the key you are making the request with, including the company, scopes, expiry date and limits. Use this endpoint to test your connection: it requires no scope.", "tags": [ "API key" ], "x-klantly-scope": null, "externalDocs": { "url": "https://developers.klantly.com/en/reference/api-key#me" }, "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "schema": { "type": "string" } }, "ETag": { "description": "Version of the object, for 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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/company": { "get": { "operationId": "companyGet", "summary": "Retrieve the company", "description": "The details of the company the key belongs to, including the default VAT rate and whether prices include VAT.", "tags": [ "Company" ], "x-klantly-scope": "company.read", "externalDocs": { "url": "https://developers.klantly.com/en/reference/company#companyget" }, "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "schema": { "type": "string" } }, "ETag": { "description": "Version of the object, for 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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This API key has no access to this action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "This API key has no access to this action.", "status": 403, "code": "insufficient_scope", "detail": "This requires the scope customers.write. Change the key's scopes in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/users": { "get": { "operationId": "usersList", "summary": "List users", "description": "The users of your company, ordered by id. Use the id as assigned_user_id on a deal.", "tags": [ "Users" ], "x-klantly-scope": "users.read", "externalDocs": { "url": "https://developers.klantly.com/en/reference/users#userslist" }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Number of results per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor or prev_cursor from meta of the previous response.", "schema": { "type": "string" } }, { "name": "filter[status]", "in": "query", "required": false, "description": "Only active or only deactivated users.", "schema": { "type": "string", "enum": [ "active", "inactive" ] } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This API key has no access to this action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "This API key has no access to this action.", "status": 403, "code": "insufficient_scope", "detail": "This requires the scope customers.write. Change the key's scopes in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "The input is invalid.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "The input is invalid.", "status": 422, "code": "validation_failed", "detail": "1 field is invalid.", "errors": { "email": [ "The email field must be a valid email address." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/customers": { "get": { "operationId": "customersList", "summary": "List customers", "description": "A list of customers and leads, newest first. Filter by status, type, email address or modification date, search with q and page with the cursor from meta.", "tags": [ "Customers" ], "x-klantly-scope": "customers.read", "externalDocs": { "url": "https://developers.klantly.com/en/reference/customers#customerslist" }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Number of results per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor or prev_cursor from meta of the previous response.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Search in name, email address, company name and phone number.", "schema": { "type": "string", "minLength": 2, "maxLength": 100 } }, { "name": "sort", "in": "query", "required": false, "description": "Sort by created_at or updated_at; a leading minus sign sorts descending.", "schema": { "type": "string", "enum": [ "-created_at", "created_at", "-updated_at", "updated_at" ], "default": "-created_at" } }, { "name": "filter[status]", "in": "query", "required": false, "description": "Only leads or only customers.", "schema": { "type": "string", "enum": [ "lead", "customer" ] } }, { "name": "filter[type]", "in": "query", "required": false, "description": "Only individuals or only businesses.", "schema": { "type": "string", "enum": [ "individual", "business" ] } }, { "name": "filter[email]", "in": "query", "required": false, "description": "Exactly this email address (case-insensitive).", "schema": { "type": "string", "format": "email" } }, { "name": "filter[updated_since]", "in": "query", "required": false, "description": "Only what changed since this moment: ISO 8601 with a time zone, for example 2026-09-14T10:15:00Z. Useful for synchronising.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This API key has no access to this action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "This API key has no access to this action.", "status": 403, "code": "insufficient_scope", "detail": "This requires the scope customers.write. Change the key's scopes in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "The input is invalid.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "The input is invalid.", "status": 422, "code": "validation_failed", "detail": "1 field is invalid.", "errors": { "email": [ "The email field must be a valid email address." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "post": { "operationId": "customersCreate", "summary": "Create a customer", "description": "Creates a new lead. The email address is required and unique within your company: an existing address returns a validation error. Automations and the customer timeline work exactly as when creating a customer in Klantly itself.", "tags": [ "Customers" ], "x-klantly-scope": "customers.write", "externalDocs": { "url": "https://developers.klantly.com/en/reference/customers#customerscreate" }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A unique key per request (for example a UUID): a retry will then not create a duplicate record. Valid for 24 hours.", "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": "Created", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "schema": { "type": "string" } }, "ETag": { "description": "Version of the object, for 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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This API key has no access to this action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "This API key has no access to this action.", "status": 403, "code": "insufficient_scope", "detail": "This requires the scope customers.write. Change the key's scopes in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "limit_reached": { "summary": "The subscription limit has been reached.", "value": { "type": "https://developers.klantly.com/errors/limit_reached", "title": "The subscription limit has been reached.", "status": 403, "code": "limit_reached", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "A request with this Idempotency-Key is still in progress.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "A request with this Idempotency-Key is still in progress.", "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": "The request body is too large.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "The request body is too large.", "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": "This format is not supported.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "This format is not supported.", "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": "The input is invalid.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "The input is invalid.", "status": 422, "code": "validation_failed", "detail": "1 field is invalid.", "errors": { "email": [ "The email field must be a valid email address." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "The input contains an unknown field.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "The input contains an unknown field.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_key_reused": { "summary": "This Idempotency-Key was already used for a different request.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "This Idempotency-Key was already used for a different request.", "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": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/customers/{customer}": { "get": { "operationId": "customersGet", "summary": "Retrieve a customer", "description": "A single customer by id. The response contains an ETag you can send in If-Match when updating.", "tags": [ "Customers" ], "x-klantly-scope": "customers.read", "externalDocs": { "url": "https://developers.klantly.com/en/reference/customers#customersget" }, "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "The id (UUID) of the customer.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "schema": { "type": "string" } }, "ETag": { "description": "Version of the object, for 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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This API key has no access to this action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "This API key has no access to this action.", "status": 403, "code": "insufficient_scope", "detail": "This requires the scope customers.write. Change the key's scopes in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "Not found.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Not found.", "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": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "patch": { "operationId": "customersUpdate", "summary": "Update a customer", "description": "Changes only the fields you send. The status does not change through this endpoint; use Convert a lead into a customer for that.", "tags": [ "Customers" ], "x-klantly-scope": "customers.write", "externalDocs": { "url": "https://developers.klantly.com/en/reference/customers#customersupdate" }, "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "The id (UUID) of the customer.", "schema": { "type": "string", "format": "uuid" } }, { "name": "If-Match", "in": "header", "required": false, "description": "The ETag of the version you retrieved. If the record changed in the meantime, you get 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": "Success", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "schema": { "type": "string" } }, "ETag": { "description": "Version of the object, for 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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This API key has no access to this action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "This API key has no access to this action.", "status": 403, "code": "insufficient_scope", "detail": "This requires the scope customers.write. Change the key's scopes in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "Not found.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Not found.", "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": "The record has been changed in the meantime.", "value": { "type": "https://developers.klantly.com/errors/precondition_failed", "title": "The record has been changed in the meantime.", "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": "The request body is too large.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "The request body is too large.", "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": "This format is not supported.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "This format is not supported.", "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": "The input is invalid.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "The input is invalid.", "status": 422, "code": "validation_failed", "detail": "1 field is invalid.", "errors": { "email": [ "The email field must be a valid email address." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "The input contains an unknown field.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "The input contains an unknown field.", "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": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/customers/{customer}/convert": { "post": { "operationId": "customersConvert", "summary": "Convert a lead into a customer", "description": "Converts a lead into a customer. If it already is a customer, nothing changes and you simply get the customer back.", "tags": [ "Customers" ], "x-klantly-scope": "customers.write", "externalDocs": { "url": "https://developers.klantly.com/en/reference/customers#customersconvert" }, "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "The id (UUID) of the customer.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A unique key per request (for example a UUID): a retry will then not create a duplicate record. Valid for 24 hours.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "schema": { "type": "string" } }, "ETag": { "description": "Version of the object, for 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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This API key has no access to this action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "This API key has no access to this action.", "status": 403, "code": "insufficient_scope", "detail": "This requires the scope customers.write. Change the key's scopes in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "Not found.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Not found.", "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": "A request with this Idempotency-Key is still in progress.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "A request with this Idempotency-Key is still in progress.", "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": "This Idempotency-Key was already used for a different request.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "This Idempotency-Key was already used for a different request.", "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": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/customers/{customer}/activities": { "get": { "operationId": "customersActivities", "summary": "Customer timeline", "description": "The timeline of a customer, newest first: quotes, invoices, appointments, emails and more. References to linked records are under related.", "tags": [ "Customers" ], "x-klantly-scope": "customers.read", "externalDocs": { "url": "https://developers.klantly.com/en/reference/customers#customersactivities" }, "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "The id (UUID) of the customer.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of results per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor or prev_cursor from meta of the previous response.", "schema": { "type": "string" } }, { "name": "filter[type]", "in": "query", "required": false, "description": "Only activities of this type, for example quote_sent or invoice_created.", "schema": { "type": "string", "maxLength": 40 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This API key has no access to this action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "This API key has no access to this action.", "status": 403, "code": "insufficient_scope", "detail": "This requires the scope customers.write. Change the key's scopes in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "Not found.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Not found.", "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": "The input is invalid.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "The input is invalid.", "status": 422, "code": "validation_failed", "detail": "1 field is invalid.", "errors": { "email": [ "The email field must be a valid email address." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/customers/{customer}/notes": { "get": { "operationId": "notesListCustomer", "summary": "List notes on a customer", "description": "The notes on a customer, newest first.", "tags": [ "Notes" ], "x-klantly-scope": "customers.read", "externalDocs": { "url": "https://developers.klantly.com/en/reference/notes#noteslist-customer" }, "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "The id (UUID) of the customer.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of results per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor or prev_cursor from meta of the previous response.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This API key has no access to this action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "This API key has no access to this action.", "status": 403, "code": "insufficient_scope", "detail": "This requires the scope customers.write. Change the key's scopes in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "Not found.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Not found.", "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": "The input is invalid.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "The input is invalid.", "status": 422, "code": "validation_failed", "detail": "1 field is invalid.", "errors": { "email": [ "The email field must be a valid email address." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "post": { "operationId": "notesCreateCustomer", "summary": "Add a note to a customer", "description": "Adds an internal note to a customer. It shows up in Klantly right away. A note added through the API has no author.", "tags": [ "Notes" ], "x-klantly-scope": "customers.write", "externalDocs": { "url": "https://developers.klantly.com/en/reference/notes#notescreate-customer" }, "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "The id (UUID) of the customer.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A unique key per request (for example a UUID): a retry will then not create a duplicate record. Valid for 24 hours.", "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": "Created", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "schema": { "type": "string" } }, "ETag": { "description": "Version of the object, for 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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This API key has no access to this action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "This API key has no access to this action.", "status": 403, "code": "insufficient_scope", "detail": "This requires the scope customers.write. Change the key's scopes in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "Not found.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Not found.", "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": "A request with this Idempotency-Key is still in progress.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "A request with this Idempotency-Key is still in progress.", "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": "The request body is too large.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "The request body is too large.", "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": "This format is not supported.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "This format is not supported.", "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": "The input is invalid.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "The input is invalid.", "status": 422, "code": "validation_failed", "detail": "1 field is invalid.", "errors": { "email": [ "The email field must be a valid email address." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "The input contains an unknown field.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "The input contains an unknown field.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_key_reused": { "summary": "This Idempotency-Key was already used for a different request.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "This Idempotency-Key was already used for a different request.", "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": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/customers/{customer}/notes/{note}": { "patch": { "operationId": "notesUpdateCustomer", "summary": "Update a note on a customer", "description": "Changes only the fields you send.", "tags": [ "Notes" ], "x-klantly-scope": "customers.write", "externalDocs": { "url": "https://developers.klantly.com/en/reference/notes#notesupdate-customer" }, "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "The id (UUID) of the customer.", "schema": { "type": "string", "format": "uuid" } }, { "name": "note", "in": "path", "required": true, "description": "The id (UUID) of the note.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotesUpdateCustomerRequest" }, "example": { "is_important": false } } } }, "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "schema": { "type": "string" } }, "ETag": { "description": "Version of the object, for 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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This API key has no access to this action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "This API key has no access to this action.", "status": 403, "code": "insufficient_scope", "detail": "This requires the scope customers.write. Change the key's scopes in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "Not found.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Not found.", "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": "The request body is too large.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "The request body is too large.", "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": "This format is not supported.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "This format is not supported.", "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": "The input is invalid.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "The input is invalid.", "status": 422, "code": "validation_failed", "detail": "1 field is invalid.", "errors": { "email": [ "The email field must be a valid email address." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "The input contains an unknown field.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "The input contains an unknown field.", "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": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "delete": { "operationId": "notesDeleteCustomer", "summary": "Delete a note on a customer", "description": "Deletes the note and its attachments. This cannot be undone.", "tags": [ "Notes" ], "x-klantly-scope": "customers.write", "externalDocs": { "url": "https://developers.klantly.com/en/reference/notes#notesdelete-customer" }, "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "The id (UUID) of the customer.", "schema": { "type": "string", "format": "uuid" } }, { "name": "note", "in": "path", "required": true, "description": "The id (UUID) of the note.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "schema": { "type": "string" } }, "ETag": { "description": "Version of the object, for 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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This API key has no access to this action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "This API key has no access to this action.", "status": 403, "code": "insufficient_scope", "detail": "This requires the scope customers.write. Change the key's scopes in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "Not found.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Not found.", "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": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals/{deal}/notes": { "get": { "operationId": "notesListDeal", "summary": "List notes on a deal", "description": "The notes on a deal, newest first.", "tags": [ "Notes" ], "x-klantly-scope": "deals.read", "externalDocs": { "url": "https://developers.klantly.com/en/reference/notes#noteslist-deal" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "The id (UUID) of the deal.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of results per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor or prev_cursor from meta of the previous response.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This API key has no access to this action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "This API key has no access to this action.", "status": 403, "code": "insufficient_scope", "detail": "This requires the scope customers.write. Change the key's scopes in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "Not found.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Not found.", "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": "The input is invalid.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "The input is invalid.", "status": 422, "code": "validation_failed", "detail": "1 field is invalid.", "errors": { "email": [ "The email field must be a valid email address." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "post": { "operationId": "notesCreateDeal", "summary": "Add a note to a deal", "description": "Adds an internal note to a deal. It shows up in Klantly right away. A note added through the API has no author.", "tags": [ "Notes" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/en/reference/notes#notescreate-deal" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "The id (UUID) of the deal.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A unique key per request (for example a UUID): a retry will then not create a duplicate record. Valid for 24 hours.", "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": "Created", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "schema": { "type": "string" } }, "ETag": { "description": "Version of the object, for 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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This API key has no access to this action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "This API key has no access to this action.", "status": 403, "code": "insufficient_scope", "detail": "This requires the scope customers.write. Change the key's scopes in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "Not found.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Not found.", "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": "A request with this Idempotency-Key is still in progress.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "A request with this Idempotency-Key is still in progress.", "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": "The request body is too large.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "The request body is too large.", "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": "This format is not supported.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "This format is not supported.", "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": "The input is invalid.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "The input is invalid.", "status": 422, "code": "validation_failed", "detail": "1 field is invalid.", "errors": { "email": [ "The email field must be a valid email address." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "The input contains an unknown field.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "The input contains an unknown field.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_key_reused": { "summary": "This Idempotency-Key was already used for a different request.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "This Idempotency-Key was already used for a different request.", "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": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals/{deal}/notes/{note}": { "patch": { "operationId": "notesUpdateDeal", "summary": "Update a note on a deal", "description": "Changes only the fields you send.", "tags": [ "Notes" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/en/reference/notes#notesupdate-deal" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "The id (UUID) of the deal.", "schema": { "type": "string", "format": "uuid" } }, { "name": "note", "in": "path", "required": true, "description": "The id (UUID) of the note.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotesUpdateDealRequest" }, "example": { "is_important": false } } } }, "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "schema": { "type": "string" } }, "ETag": { "description": "Version of the object, for 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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This API key has no access to this action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "This API key has no access to this action.", "status": 403, "code": "insufficient_scope", "detail": "This requires the scope customers.write. Change the key's scopes in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "Not found.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Not found.", "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": "The request body is too large.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "The request body is too large.", "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": "This format is not supported.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "This format is not supported.", "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": "The input is invalid.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "The input is invalid.", "status": 422, "code": "validation_failed", "detail": "1 field is invalid.", "errors": { "email": [ "The email field must be a valid email address." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "The input contains an unknown field.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "The input contains an unknown field.", "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": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "delete": { "operationId": "notesDeleteDeal", "summary": "Delete a note on a deal", "description": "Deletes the note and its attachments. This cannot be undone.", "tags": [ "Notes" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/en/reference/notes#notesdelete-deal" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "The id (UUID) of the deal.", "schema": { "type": "string", "format": "uuid" } }, { "name": "note", "in": "path", "required": true, "description": "The id (UUID) of the note.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "schema": { "type": "string" } }, "ETag": { "description": "Version of the object, for 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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This API key has no access to this action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "This API key has no access to this action.", "status": 403, "code": "insufficient_scope", "detail": "This requires the scope customers.write. Change the key's scopes in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "Not found.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Not found.", "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": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/pipeline-stages": { "get": { "operationId": "pipelineStagesList", "summary": "List pipeline stages", "description": "All active stages of the pipeline board, in board order. The names in all four languages are under names.", "tags": [ "Pipeline stages" ], "x-klantly-scope": "deals.read", "externalDocs": { "url": "https://developers.klantly.com/en/reference/pipeline-stages#pipeline-stageslist" }, "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This API key has no access to this action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "This API key has no access to this action.", "status": 403, "code": "insufficient_scope", "detail": "This requires the scope customers.write. Change the key's scopes in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals": { "get": { "operationId": "dealsList", "summary": "List deals", "description": "A list of deals, newest first. Archived deals are left out by default; use filter[archived] to include them. Filter by status, stage, customer, owner or modification date.", "tags": [ "Deals" ], "x-klantly-scope": "deals.read", "externalDocs": { "url": "https://developers.klantly.com/en/reference/deals#dealslist" }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Number of results per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor or prev_cursor from meta of the previous response.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort by created_at, updated_at or stage_changed_at; a minus sign in front means descending.", "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": "Only open, won or lost deals.", "schema": { "type": "string", "enum": [ "open", "won", "lost" ] } }, { "name": "filter[stage_id]", "in": "query", "required": false, "description": "Only deals in this stage (the id from List pipeline stages).", "schema": { "type": "integer" } }, { "name": "filter[customer_id]", "in": "query", "required": false, "description": "Only deals of this customer.", "schema": { "type": "string", "format": "uuid" } }, { "name": "filter[assigned_user_id]", "in": "query", "required": false, "description": "Only deals assigned to this user.", "schema": { "type": "integer" } }, { "name": "filter[archived]", "in": "query", "required": false, "description": "false (default) shows only deals on the board, true only archived ones, all both.", "schema": { "type": "string", "enum": [ "false", "true", "all" ], "default": "false" } }, { "name": "filter[updated_since]", "in": "query", "required": false, "description": "Only what changed since this moment: ISO 8601 with a time zone, for example 2026-09-14T10:15:00Z. Useful for synchronising.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This API key has no access to this action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "This API key has no access to this action.", "status": 403, "code": "insufficient_scope", "detail": "This requires the scope customers.write. Change the key's scopes in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "The input is invalid.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "The input is invalid.", "status": 422, "code": "validation_failed", "detail": "1 field is invalid.", "errors": { "email": [ "The email field must be a valid email address." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "post": { "operationId": "dealsCreate", "summary": "Create a deal", "description": "Puts a customer on the pipeline board. A customer can have only one open deal at a time: if there already is one, you get 409 with its id in deal_id. Without stage_id the deal lands in the default stage. If you send value, Klantly keeps that amount instead of calculating it from the quotes.", "tags": [ "Deals" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/en/reference/deals#dealscreate" }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A unique key per request (for example a UUID): a retry will then not create a duplicate record. Valid for 24 hours.", "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": "Created", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "schema": { "type": "string" } }, "ETag": { "description": "Version of the object, for 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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This API key has no access to this action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "This API key has no access to this action.", "status": 403, "code": "insufficient_scope", "detail": "This requires the scope customers.write. Change the key's scopes in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "This conflicts with the current state.", "value": { "type": "https://developers.klantly.com/errors/conflict", "title": "This conflicts with the current state.", "status": 409, "code": "conflict", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_in_progress": { "summary": "A request with this Idempotency-Key is still in progress.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "A request with this Idempotency-Key is still in progress.", "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": "The request body is too large.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "The request body is too large.", "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": "This format is not supported.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "This format is not supported.", "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": "The input is invalid.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "The input is invalid.", "status": 422, "code": "validation_failed", "detail": "1 field is invalid.", "errors": { "email": [ "The email field must be a valid email address." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "The input contains an unknown field.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "The input contains an unknown field.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_key_reused": { "summary": "This Idempotency-Key was already used for a different request.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "This Idempotency-Key was already used for a different request.", "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": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals/{deal}": { "get": { "operationId": "dealsGet", "summary": "Retrieve a deal", "description": "One deal by id. The response includes an ETag you can send in If-Match when updating.", "tags": [ "Deals" ], "x-klantly-scope": "deals.read", "externalDocs": { "url": "https://developers.klantly.com/en/reference/deals#dealsget" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "The id (UUID) of the deal.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "schema": { "type": "string" } }, "ETag": { "description": "Version of the object, for 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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This API key has no access to this action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "This API key has no access to this action.", "status": 403, "code": "insufficient_scope", "detail": "This requires the scope customers.write. Change the key's scopes in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "Not found.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Not found.", "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": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "patch": { "operationId": "dealsUpdate", "summary": "Update a deal", "description": "Changes only the fields you send. To change the stage, use move, win or lose. Sending value sets value_source to manual.", "tags": [ "Deals" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/en/reference/deals#dealsupdate" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "The id (UUID) of the deal.", "schema": { "type": "string", "format": "uuid" } }, { "name": "If-Match", "in": "header", "required": false, "description": "The ETag of the version you retrieved. If the record changed in the meantime, you get 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": "Success", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "schema": { "type": "string" } }, "ETag": { "description": "Version of the object, for 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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This API key has no access to this action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "This API key has no access to this action.", "status": 403, "code": "insufficient_scope", "detail": "This requires the scope customers.write. Change the key's scopes in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "Not found.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Not found.", "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": "The record has been changed in the meantime.", "value": { "type": "https://developers.klantly.com/errors/precondition_failed", "title": "The record has been changed in the meantime.", "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": "The request body is too large.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "The request body is too large.", "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": "This format is not supported.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "This format is not supported.", "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": "The input is invalid.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "The input is invalid.", "status": 422, "code": "validation_failed", "detail": "1 field is invalid.", "errors": { "email": [ "The email field must be a valid email address." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "The input contains an unknown field.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "The input contains an unknown field.", "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": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals/{deal}/move": { "post": { "operationId": "dealsMove", "summary": "Move a deal", "description": "Moves the deal to another stage, exactly like dragging it on the board. If that is a won or lost stage, the deal becomes won or lost too.", "tags": [ "Deals" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/en/reference/deals#dealsmove" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "The id (UUID) of the deal.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A unique key per request (for example a UUID): a retry will then not create a duplicate record. Valid for 24 hours.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealsMoveRequest" }, "example": { "stage_id": 3 } } } }, "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "schema": { "type": "string" } }, "ETag": { "description": "Version of the object, for 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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This API key has no access to this action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "This API key has no access to this action.", "status": 403, "code": "insufficient_scope", "detail": "This requires the scope customers.write. Change the key's scopes in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "Not found.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Not found.", "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": "A request with this Idempotency-Key is still in progress.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "A request with this Idempotency-Key is still in progress.", "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": "The request body is too large.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "The request body is too large.", "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": "This format is not supported.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "This format is not supported.", "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": "The input is invalid.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "The input is invalid.", "status": 422, "code": "validation_failed", "detail": "1 field is invalid.", "errors": { "email": [ "The email field must be a valid email address." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "The input contains an unknown field.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "The input contains an unknown field.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_key_reused": { "summary": "This Idempotency-Key was already used for a different request.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "This Idempotency-Key was already used for a different request.", "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": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals/{deal}/win": { "post": { "operationId": "dealsWin", "summary": "Win a deal", "description": "Moves the deal to the stage your company has set up as won. If it is already won, nothing changes.", "tags": [ "Deals" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/en/reference/deals#dealswin" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "The id (UUID) of the deal.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A unique key per request (for example a UUID): a retry will then not create a duplicate record. Valid for 24 hours.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "schema": { "type": "string" } }, "ETag": { "description": "Version of the object, for 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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This API key has no access to this action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "This API key has no access to this action.", "status": 403, "code": "insufficient_scope", "detail": "This requires the scope customers.write. Change the key's scopes in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "Not found.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Not found.", "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": "This action is not possible in the current status.", "value": { "type": "https://developers.klantly.com/errors/invalid_state_transition", "title": "This action is not possible in the current status.", "status": 409, "code": "invalid_state_transition", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_in_progress": { "summary": "A request with this Idempotency-Key is still in progress.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "A request with this Idempotency-Key is still in progress.", "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": "This Idempotency-Key was already used for a different request.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "This Idempotency-Key was already used for a different request.", "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": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals/{deal}/lose": { "post": { "operationId": "dealsLose", "summary": "Lose a deal", "description": "Moves the deal to the stage your company has set up as lost, optionally with a reason.", "tags": [ "Deals" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/en/reference/deals#dealslose" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "The id (UUID) of the deal.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A unique key per request (for example a UUID): a retry will then not create a duplicate record. Valid for 24 hours.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealsLoseRequest" }, "example": { "lost_reason": "Te duur" } } } }, "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "schema": { "type": "string" } }, "ETag": { "description": "Version of the object, for 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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This API key has no access to this action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "This API key has no access to this action.", "status": 403, "code": "insufficient_scope", "detail": "This requires the scope customers.write. Change the key's scopes in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "Not found.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Not found.", "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": "This action is not possible in the current status.", "value": { "type": "https://developers.klantly.com/errors/invalid_state_transition", "title": "This action is not possible in the current status.", "status": 409, "code": "invalid_state_transition", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_in_progress": { "summary": "A request with this Idempotency-Key is still in progress.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "A request with this Idempotency-Key is still in progress.", "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": "The request body is too large.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "The request body is too large.", "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": "This format is not supported.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "This format is not supported.", "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": "The input is invalid.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "The input is invalid.", "status": 422, "code": "validation_failed", "detail": "1 field is invalid.", "errors": { "email": [ "The email field must be a valid email address." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "The input contains an unknown field.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "The input contains an unknown field.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_key_reused": { "summary": "This Idempotency-Key was already used for a different request.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "This Idempotency-Key was already used for a different request.", "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": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals/{deal}/archive": { "post": { "operationId": "dealsArchive", "summary": "Archive a deal", "description": "Takes the deal off the board without deleting it. Deals cannot be deleted through the API.", "tags": [ "Deals" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/en/reference/deals#dealsarchive" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "The id (UUID) of the deal.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A unique key per request (for example a UUID): a retry will then not create a duplicate record. Valid for 24 hours.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "schema": { "type": "string" } }, "ETag": { "description": "Version of the object, for 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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This API key has no access to this action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "This API key has no access to this action.", "status": 403, "code": "insufficient_scope", "detail": "This requires the scope customers.write. Change the key's scopes in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "Not found.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Not found.", "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": "A request with this Idempotency-Key is still in progress.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "A request with this Idempotency-Key is still in progress.", "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": "This Idempotency-Key was already used for a different request.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "This Idempotency-Key was already used for a different request.", "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": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals/{deal}/unarchive": { "post": { "operationId": "dealsUnarchive", "summary": "Restore a deal", "description": "Puts an archived deal back on the board.", "tags": [ "Deals" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/en/reference/deals#dealsunarchive" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "The id (UUID) of the deal.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A unique key per request (for example a UUID): a retry will then not create a duplicate record. Valid for 24 hours.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "schema": { "type": "string" } }, "ETag": { "description": "Version of the object, for 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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This API key has no access to this action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "This API key has no access to this action.", "status": 403, "code": "insufficient_scope", "detail": "This requires the scope customers.write. Change the key's scopes in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "Not found.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Not found.", "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": "A request with this Idempotency-Key is still in progress.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "A request with this Idempotency-Key is still in progress.", "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": "This Idempotency-Key was already used for a different request.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "This Idempotency-Key was already used for a different request.", "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": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/webhook-endpoints": { "get": { "operationId": "webhookEndpointsList", "summary": "List webhook endpoints", "description": "All webhook endpoints of your company, oldest first. The secret is never included.", "tags": [ "Webhook endpoints" ], "x-klantly-scope": "webhooks.manage", "externalDocs": { "url": "https://developers.klantly.com/en/reference/webhook-endpoints#webhook-endpointslist" }, "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This API key has no access to this action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "This API key has no access to this action.", "status": 403, "code": "insufficient_scope", "detail": "This requires the scope customers.write. Change the key's scopes in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "post": { "operationId": "webhookEndpointsCreate", "summary": "Create a webhook endpoint", "description": "Registers an https URL that receives events. The response contains the secret for checking signatures: store it right away, you will not see it again. You can only choose events about data your key can read; * means every event within that, including future ones. Up to 10 endpoints per company.", "tags": [ "Webhook endpoints" ], "x-klantly-scope": "webhooks.manage", "externalDocs": { "url": "https://developers.klantly.com/en/reference/webhook-endpoints#webhook-endpointscreate" }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A unique key per request (for example a UUID): a retry will then not create a duplicate record. Valid for 24 hours.", "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": "Created", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "schema": { "type": "string" } }, "ETag": { "description": "Version of the object, for 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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This API key has no access to this action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "This API key has no access to this action.", "status": 403, "code": "insufficient_scope", "detail": "This requires the scope customers.write. Change the key's scopes in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "limit_reached": { "summary": "The subscription limit has been reached.", "value": { "type": "https://developers.klantly.com/errors/limit_reached", "title": "The subscription limit has been reached.", "status": 403, "code": "limit_reached", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "A request with this Idempotency-Key is still in progress.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "A request with this Idempotency-Key is still in progress.", "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": "The request body is too large.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "The request body is too large.", "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": "This format is not supported.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "This format is not supported.", "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": "The input is invalid.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "The input is invalid.", "status": 422, "code": "validation_failed", "detail": "1 field is invalid.", "errors": { "email": [ "The email field must be a valid email address." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "The input contains an unknown field.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "The input contains an unknown field.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_key_reused": { "summary": "This Idempotency-Key was already used for a different request.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "This Idempotency-Key was already used for a different request.", "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": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/webhook-endpoints/{endpoint}": { "get": { "operationId": "webhookEndpointsGet", "summary": "Retrieve a webhook endpoint", "description": "One endpoint by id, with its status and the time of the last successful and failed delivery.", "tags": [ "Webhook endpoints" ], "x-klantly-scope": "webhooks.manage", "externalDocs": { "url": "https://developers.klantly.com/en/reference/webhook-endpoints#webhook-endpointsget" }, "parameters": [ { "name": "endpoint", "in": "path", "required": true, "description": "The id of the webhook endpoint.", "schema": { "type": "string", "pattern": "^[0-9a-z]{26}$" } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "schema": { "type": "string" } }, "ETag": { "description": "Version of the object, for 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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This API key has no access to this action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "This API key has no access to this action.", "status": 403, "code": "insufficient_scope", "detail": "This requires the scope customers.write. Change the key's scopes in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "Not found.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Not found.", "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": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "patch": { "operationId": "webhookEndpointsUpdate", "summary": "Update a webhook endpoint", "description": "Changes only the fields you send. Use status to turn the endpoint off or back on; turning it back on resets the failure count.", "tags": [ "Webhook endpoints" ], "x-klantly-scope": "webhooks.manage", "externalDocs": { "url": "https://developers.klantly.com/en/reference/webhook-endpoints#webhook-endpointsupdate" }, "parameters": [ { "name": "endpoint", "in": "path", "required": true, "description": "The id of the webhook endpoint.", "schema": { "type": "string", "pattern": "^[0-9a-z]{26}$" } }, { "name": "If-Match", "in": "header", "required": false, "description": "The ETag of the version you retrieved. If the record changed in the meantime, you get 412.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointsUpdateRequest" }, "example": { "events": [ "*" ], "status": "active" } } } }, "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "schema": { "type": "string" } }, "ETag": { "description": "Version of the object, for 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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This API key has no access to this action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "This API key has no access to this action.", "status": 403, "code": "insufficient_scope", "detail": "This requires the scope customers.write. Change the key's scopes in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "Not found.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Not found.", "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": "The record has been changed in the meantime.", "value": { "type": "https://developers.klantly.com/errors/precondition_failed", "title": "The record has been changed in the meantime.", "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": "The request body is too large.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "The request body is too large.", "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": "This format is not supported.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "This format is not supported.", "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": "The input is invalid.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "The input is invalid.", "status": 422, "code": "validation_failed", "detail": "1 field is invalid.", "errors": { "email": [ "The email field must be a valid email address." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "The input contains an unknown field.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "The input contains an unknown field.", "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": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "delete": { "operationId": "webhookEndpointsDelete", "summary": "Delete a webhook endpoint", "description": "Deletes the endpoint. Events that are still on their way are no longer delivered.", "tags": [ "Webhook endpoints" ], "x-klantly-scope": "webhooks.manage", "externalDocs": { "url": "https://developers.klantly.com/en/reference/webhook-endpoints#webhook-endpointsdelete" }, "parameters": [ { "name": "endpoint", "in": "path", "required": true, "description": "The id of the webhook endpoint.", "schema": { "type": "string", "pattern": "^[0-9a-z]{26}$" } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "schema": { "type": "string" } }, "ETag": { "description": "Version of the object, for 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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This API key has no access to this action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "This API key has no access to this action.", "status": 403, "code": "insufficient_scope", "detail": "This requires the scope customers.write. Change the key's scopes in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "Not found.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Not found.", "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": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/webhook-endpoints/{endpoint}/test": { "post": { "operationId": "webhookEndpointsTest", "summary": "Send a test message", "description": "Sends the ping event to the endpoint right away, even if it is disabled, and returns the delivery attempt. A test message is not retried.", "tags": [ "Webhook endpoints" ], "x-klantly-scope": "webhooks.manage", "externalDocs": { "url": "https://developers.klantly.com/en/reference/webhook-endpoints#webhook-endpointstest" }, "parameters": [ { "name": "endpoint", "in": "path", "required": true, "description": "The id of the webhook endpoint.", "schema": { "type": "string", "pattern": "^[0-9a-z]{26}$" } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "schema": { "type": "string" } }, "ETag": { "description": "Version of the object, for 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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This API key has no access to this action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "This API key has no access to this action.", "status": 403, "code": "insufficient_scope", "detail": "This requires the scope customers.write. Change the key's scopes in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "Not found.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Not found.", "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": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/webhook-endpoints/{endpoint}/rotate-secret": { "post": { "operationId": "webhookEndpointsRotateSecret", "summary": "Rotate the secret", "description": "Creates a new secret and returns it once. During the overlap Klantly signs with both the old and the new secret, so your receiver can switch over without interruption.", "tags": [ "Webhook endpoints" ], "x-klantly-scope": "webhooks.manage", "externalDocs": { "url": "https://developers.klantly.com/en/reference/webhook-endpoints#webhook-endpointsrotate-secret" }, "parameters": [ { "name": "endpoint", "in": "path", "required": true, "description": "The id of the webhook endpoint.", "schema": { "type": "string", "pattern": "^[0-9a-z]{26}$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A unique key per request (for example a UUID): a retry will then not create a duplicate record. Valid for 24 hours.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointsRotateSecretRequest" }, "example": { "overlap_hours": 24 } } } }, "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "schema": { "type": "string" } }, "ETag": { "description": "Version of the object, for 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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This API key has no access to this action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "This API key has no access to this action.", "status": 403, "code": "insufficient_scope", "detail": "This requires the scope customers.write. Change the key's scopes in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "Not found.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Not found.", "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": "A request with this Idempotency-Key is still in progress.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "A request with this Idempotency-Key is still in progress.", "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": "The request body is too large.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "The request body is too large.", "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": "This format is not supported.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "This format is not supported.", "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": "The input is invalid.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "The input is invalid.", "status": 422, "code": "validation_failed", "detail": "1 field is invalid.", "errors": { "email": [ "The email field must be a valid email address." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "The input contains an unknown field.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "The input contains an unknown field.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_key_reused": { "summary": "This Idempotency-Key was already used for a different request.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "This Idempotency-Key was already used for a different request.", "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": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/events": { "get": { "operationId": "eventsList", "summary": "List events", "description": "The events of the last 30 days, newest first. You only see events about data your key can read. Use sort=created_at with filter[created_since] to catch up on missed events in order.", "tags": [ "Events" ], "x-klantly-scope": "events.read", "externalDocs": { "url": "https://developers.klantly.com/en/reference/events#eventslist" }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Number of results per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor or prev_cursor from meta of the previous response.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "created_at keeps the order in which things happened, -created_at (default) shows the newest first.", "schema": { "type": "string", "enum": [ "-created_at", "created_at" ], "default": "-created_at" } }, { "name": "filter[type]", "in": "query", "required": false, "description": "Only these event types, separated by commas, for example customer.created,deal.won.", "schema": { "type": "string", "maxLength": 500 } }, { "name": "filter[created_since]", "in": "query", "required": false, "description": "Only events from this moment on: ISO 8601 with a time zone, for example 2026-09-14T10:15:00Z.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This API key has no access to this action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "This API key has no access to this action.", "status": 403, "code": "insufficient_scope", "detail": "This requires the scope customers.write. Change the key's scopes in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "The input is invalid.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "The input is invalid.", "status": 422, "code": "validation_failed", "detail": "1 field is invalid.", "errors": { "email": [ "The email field must be a valid email address." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/events/{event}": { "get": { "operationId": "eventsGet", "summary": "Retrieve an event", "description": "One event by id, for example the webhook-id of a message you received.", "tags": [ "Events" ], "x-klantly-scope": "events.read", "externalDocs": { "url": "https://developers.klantly.com/en/reference/events#eventsget" }, "parameters": [ { "name": "event", "in": "path", "required": true, "description": "The id of the event (evt_…).", "schema": { "type": "string", "pattern": "^evt_[0-9a-z]{26}$" } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Unique id of this request. Mention it when you contact support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds until the reset of the tightest limit.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "All limits that apply to this request.", "schema": { "type": "string" } }, "ETag": { "description": "Version of the object, for 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": "Authentication required.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentication required.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Invalid API key.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Invalid API key.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "This API key has been revoked.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "This API key has been revoked.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "This API key has expired.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "This API key has expired.", "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": "This API key has no access to this action.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "This API key has no access to this action.", "status": 403, "code": "insufficient_scope", "detail": "This requires the scope customers.write. Change the key's scopes in Klantly.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "This IP address may not use this API key.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "This IP address may not use this API key.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "This company's account has been blocked.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "This company's account has been blocked.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "This company has no active subscription.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "This company has no active subscription.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "This feature is not available for this company.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "This feature is not available for this company.", "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": "Not found.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Not found.", "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": "Too many requests.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Too many requests.", "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": "Something went wrong on our side.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Something went wrong on our side.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Your company's API key (kly_…), created in Klantly under Integrations → API." } }, "schemas": { "Problem": { "type": "object", "description": "An error according to RFC 9457 (problem details).", "required": [ "type", "title", "status", "code" ], "properties": { "type": { "type": "string", "format": "uri", "description": "URL of the page that explains this error." }, "title": { "type": "string", "description": "Short description, in the language of the request." }, "status": { "type": "integer", "description": "HTTP status code." }, "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": "Fixed, English error code: program against this." }, "detail": { "type": "string", "description": "Explanation of this specific error." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Validation errors per field." }, "request_id": { "type": "string", "description": "Id of the request, for support." } } }, "ListMeta": { "type": "object", "required": [ "limit", "next_cursor", "prev_cursor" ], "properties": { "limit": { "type": "integer", "description": "Number of results per page.", "examples": [ 50 ] }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null on the last page.", "examples": [ "eyJpZCI6IjlkM2Y2YzFlIn0" ] }, "prev_cursor": { "type": [ "string", "null" ], "description": "Cursor for the previous page, or null on the first page.", "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": "Always \"customer\".", "examples": [ "customer" ] }, "id": { "type": "string", "format": "uuid", "description": "Unique id (UUID).", "examples": [ "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" ] }, "type": { "type": "string", "enum": [ "individual", "business" ], "description": "individual or business.", "examples": [ "business" ] }, "status": { "type": "string", "enum": [ "lead", "customer" ], "description": "lead or customer.", "examples": [ "lead" ] }, "name": { "type": [ "string", "null" ], "description": "Name of the contact person.", "examples": [ "Jan de Vries" ] }, "email": { "type": "string", "format": "email", "description": "Email address; unique within your company.", "examples": [ "jan@example.com" ] }, "phone": { "type": [ "string", "null" ], "description": "Phone number.", "examples": [ "+31 6 12345678" ] }, "company_name": { "type": [ "string", "null" ], "description": "Company name, for a business customer.", "examples": [ "De Vries Bouw" ] }, "vat_number": { "type": [ "string", "null" ], "description": "VAT number.", "examples": [ "NL123456789B01" ] }, "coc_number": { "type": [ "string", "null" ], "description": "Chamber of Commerce number.", "examples": [ "12345678" ] }, "address": { "type": [ "string", "null" ], "description": "Street and house number.", "examples": [ "Dorpsstraat 1" ] }, "postal_code": { "type": [ "string", "null" ], "description": "Postal code.", "examples": [ "3511 AB" ] }, "city": { "type": [ "string", "null" ], "description": "City.", "examples": [ "Utrecht" ] }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Country.", "examples": [ "NL" ] }, "email_unsubscribed": { "type": "boolean", "description": "Has unsubscribed from email.", "examples": [ false ] }, "converted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the lead became a customer.", "examples": [ null ] }, "last_activity_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Last activity in Klantly.", "examples": [ "2026-09-14T10:15:00Z" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Created at (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Last updated at (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": "Always \"api_key\".", "examples": [ "api_key" ] }, "id": { "type": "string", "description": "Id of the key.", "examples": [ "01j7zq3k9x2m4n6p8r0t2v4w6y" ] }, "name": { "type": "string", "description": "The name the key was given in Klantly.", "examples": [ "Website" ] }, "prefix": { "type": "string", "description": "The start of the key, to recognise it.", "examples": [ "kly_4fZ2mQ8v" ] }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "The scopes of the key.", "examples": [ [ "customers.read", "customers.write" ] ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Expiry date, or null if the key does not expire.", "examples": [ "2027-09-14T10:15:00Z" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Created at (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "company": { "description": "The company the key belongs to.", "type": "object", "required": [ "object", "id", "name" ], "properties": { "object": { "type": "string", "const": "company", "description": "Always \"company\".", "examples": [ "company" ] }, "id": { "type": "string", "description": "Id of the company.", "examples": [ "42" ] }, "name": { "type": "string", "description": "Name of the company.", "examples": [ "De Vries Bouw" ] } }, "additionalProperties": false }, "rate_limits": { "type": "array", "items": { "type": "object", "required": [ "name", "limit", "window_seconds" ], "properties": { "name": { "type": "string", "description": "Name of the limit.", "examples": [ "key_minute" ] }, "limit": { "type": "integer", "description": "Maximum number of requests in the window.", "examples": [ 120 ] }, "window_seconds": { "type": "integer", "description": "Length of the window in seconds.", "examples": [ 60 ] } }, "additionalProperties": false }, "description": "The limits that apply to this key.", "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": "Always \"company\".", "examples": [ "company" ] }, "id": { "type": "string", "description": "Id of the company.", "examples": [ "42" ] }, "name": { "type": "string", "description": "Company name.", "examples": [ "De Vries Bouw" ] }, "email": { "type": [ "string", "null" ], "description": "General email address.", "examples": [ "info@devriesbouw.nl" ] }, "phone": { "type": [ "string", "null" ], "description": "Phone number.", "examples": [ "+31 30 1234567" ] }, "website": { "type": [ "string", "null" ], "description": "Website.", "examples": [ "https://devriesbouw.nl" ] }, "coc_number": { "type": [ "string", "null" ], "description": "Chamber of Commerce number.", "examples": [ "12345678" ] }, "vat_number": { "type": [ "string", "null" ], "description": "VAT number.", "examples": [ "NL123456789B01" ] }, "address": { "type": [ "string", "null" ], "description": "Street and house number.", "examples": [ "Industrieweg 5" ] }, "postal_code": { "type": [ "string", "null" ], "description": "Postal code.", "examples": [ "3542 AD" ] }, "city": { "type": [ "string", "null" ], "description": "City.", "examples": [ "Utrecht" ] }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Country, as a two-letter ISO code (for example NL).", "examples": [ "NL" ] }, "language": { "type": "string", "enum": [ "nl", "en", "de", "fr" ], "description": "Main language of the company.", "examples": [ "nl" ] }, "currency": { "type": "string", "const": "EUR", "description": "Always \"EUR\".", "examples": [ "EUR" ] }, "timezone": { "type": "string", "description": "Time zone in which Klantly shows times to the company. The API always returns times in UTC.", "examples": [ "Europe/Amsterdam" ] }, "default_vat_rate": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "description": "Default VAT percentage, as a string with two decimals.", "examples": [ "21.00" ] }, "prices_include_vat": { "type": "boolean", "description": "Whether prices are entered including VAT by default.", "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": "Always \"user\".", "examples": [ "user" ] }, "id": { "type": "string", "description": "Id of the user.", "examples": [ "7" ] }, "name": { "type": "string", "description": "Name.", "examples": [ "Sanne Bakker" ] }, "email": { "type": "string", "format": "email", "description": "Email address.", "examples": [ "sanne@devriesbouw.nl" ] }, "role": { "type": [ "string", "null" ], "description": "Name of the role in your company, or null without a role.", "examples": [ "Verkoop" ] }, "is_owner": { "type": "boolean", "description": "The owner of the account.", "examples": [ false ] }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "active or inactive (deactivated).", "examples": [ "active" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Created at (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": "Always \"customer_activity\".", "examples": [ "customer_activity" ] }, "id": { "type": "string", "format": "uuid", "description": "Unique id (UUID).", "examples": [ "9d3f7c62-3e7a-4f9d-8c4b-5a6e7f8a9ba3" ] }, "customer_id": { "type": "string", "format": "uuid", "description": "The customer the activity belongs to.", "examples": [ "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" ] }, "type": { "type": "string", "description": "Kind of activity, for example quote_sent, invoice_created or appointment_created. New kinds can be added: handle an unknown value gracefully.", "examples": [ "quote_sent" ] }, "title": { "type": [ "string", "null" ], "description": "Short description.", "examples": [ null ] }, "description": { "type": [ "string", "null" ], "description": "Details.", "examples": [ null ] }, "related": { "description": "References to linked records; only the ones that apply have a value.", "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 of the linked quote.", "examples": [ null ] }, "invoice_id": { "type": [ "string", "null" ], "description": "Id of the linked invoice.", "examples": [ null ] }, "appointment_id": { "type": [ "string", "null" ], "description": "Id of the linked appointment.", "examples": [ null ] }, "work_order_id": { "type": [ "string", "null" ], "description": "Id of the linked work order.", "examples": [ null ] }, "task_id": { "type": [ "string", "null" ], "description": "Id of the linked task.", "examples": [ null ] }, "deal_id": { "type": [ "string", "null" ], "description": "Id of the linked deal.", "examples": [ null ] }, "order_id": { "type": [ "string", "null" ], "description": "Id of the linked order.", "examples": [ null ] }, "conversation_id": { "type": [ "string", "null" ], "description": "Id of the linked conversation.", "examples": [ null ] } }, "additionalProperties": false }, "happened_at": { "type": "string", "format": "date-time", "description": "When it happened (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Recorded at (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": "Always \"note\".", "examples": [ "note" ] }, "id": { "type": "string", "format": "uuid", "description": "Unique id (UUID).", "examples": [ "9d3f7b41-2d6f-4e8c-9b3a-4f5d6e7a8b92" ] }, "content": { "type": "string", "description": "The text of the note.", "examples": [ "Klant belt terug na de vakantie." ] }, "is_important": { "type": "boolean", "description": "Marked as important.", "examples": [ true ] }, "parent": { "description": "What the note belongs to.", "type": "object", "required": [ "object", "id" ], "properties": { "object": { "type": "string", "enum": [ "customer", "deal" ], "description": "\"customer\" or \"deal\".", "examples": [ "customer" ] }, "id": { "type": "string", "format": "uuid", "description": "Id of the customer or deal.", "examples": [ "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" ] } }, "additionalProperties": false }, "author": { "description": "Who wrote the note, or null for a note added through the API.", "type": [ "object", "null" ], "required": [ "object", "id", "name" ], "properties": { "object": { "type": "string", "const": "user", "description": "Always \"user\".", "examples": [ "user" ] }, "id": { "type": "string", "description": "Id of the user.", "examples": [ "7" ] }, "name": { "type": "string", "description": "Name of the user.", "examples": [ "Sanne Bakker" ] } }, "additionalProperties": false }, "created_at": { "type": "string", "format": "date-time", "description": "Created at (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Last updated at (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": "Always \"pipeline_stage\".", "examples": [ "pipeline_stage" ] }, "id": { "type": "string", "description": "Id of the stage.", "examples": [ "3" ] }, "name": { "type": "string", "description": "Name in the language of the request.", "examples": [ "Offerte verstuurd" ] }, "names": { "description": "The name in all four languages.", "type": "object", "required": [ "nl", "en", "de", "fr" ], "properties": { "nl": { "type": [ "string", "null" ], "description": "Dutch name.", "examples": [ "Offerte verstuurd" ] }, "en": { "type": [ "string", "null" ], "description": "English name.", "examples": [ "Quote sent" ] }, "de": { "type": [ "string", "null" ], "description": "German name.", "examples": [ "Angebot gesendet" ] }, "fr": { "type": [ "string", "null" ], "description": "French name.", "examples": [ "Devis envoyé" ] } }, "additionalProperties": false }, "type": { "type": "string", "enum": [ "open", "won", "lost" ], "description": "open, won or lost: a deal in this stage gets that status.", "examples": [ "open" ] }, "is_default": { "type": "boolean", "description": "New deals land in this stage.", "examples": [ false ] }, "position": { "type": "integer", "description": "Position on the board, from left to right.", "examples": [ 3 ] }, "probability": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "description": "Chance of winning as a percentage, as a string with two decimals.", "examples": [ "50.00" ] }, "color": { "type": [ "string", "null" ], "description": "Colour on the board (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": "Always \"deal\".", "examples": [ "deal" ] }, "id": { "type": "string", "format": "uuid", "description": "Unique id (UUID).", "examples": [ "9d3f7a20-1c5e-4d7b-8a2f-3e4c5d6f7a81" ] }, "title": { "type": "string", "description": "Title of the deal.", "examples": [ "Veranda 5x3 m" ] }, "description": { "type": [ "string", "null" ], "description": "Description.", "examples": [ null ] }, "status": { "type": "string", "enum": [ "open", "won", "lost" ], "description": "open, won or lost; follows from the stage.", "examples": [ "open" ] }, "value": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "description": "Value as a string with two decimals, for example \"8450.00\". When creating or updating you may also send a number.", "examples": [ "8450.00" ] }, "currency": { "type": "string", "const": "EUR", "description": "Always \"EUR\".", "examples": [ "EUR" ] }, "value_source": { "type": "string", "enum": [ "quotes", "manual" ], "description": "quotes: the value follows from the linked quotes; manual: set by hand.", "examples": [ "manual" ] }, "stage": { "description": "The stage the deal is in; the names are in List pipeline stages.", "type": [ "object", "null" ], "required": [ "object", "id" ], "properties": { "object": { "type": "string", "const": "pipeline_stage", "description": "Always \"pipeline_stage\".", "examples": [ "pipeline_stage" ] }, "id": { "type": "string", "description": "Id of the stage.", "examples": [ "3" ] } }, "additionalProperties": false }, "customer_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The customer of the deal.", "examples": [ "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" ] }, "assigned_user_id": { "type": [ "string", "null" ], "description": "The user handling the deal, or null.", "examples": [ "7" ] }, "source": { "type": [ "string", "null" ], "description": "Where the deal came from; through the API that is api.", "examples": [ "api" ] }, "lost_reason": { "type": [ "string", "null" ], "description": "Why the deal was lost, or null.", "examples": [ null ] }, "is_archived": { "type": "boolean", "description": "Archived: no longer on the board.", "examples": [ false ] }, "stage_changed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the deal last changed stage.", "examples": [ "2026-09-14T10:15:00Z" ] }, "won_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the deal was won.", "examples": [ null ] }, "lost_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the deal was lost.", "examples": [ null ] }, "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the deal was archived.", "examples": [ null ] }, "created_at": { "type": "string", "format": "date-time", "description": "Created at (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Last updated at (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] } }, "additionalProperties": false }, "DealAction": { "type": "object", "required": [ "stage_id", "notes" ], "properties": { "stage_id": { "type": "integer", "description": "The id of the stage the deal moves to (from List pipeline stages).", "examples": [ 3 ] }, "notes": { "type": [ "string", "null" ], "description": "Optional note; kept in the history of the deal together with the stage change.", "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": "Always \"webhook_endpoint\".", "examples": [ "webhook_endpoint" ] }, "id": { "type": "string", "description": "Id of the endpoint.", "examples": [ "01j7zr8m2k4n6p8r0t2v4w6y8a" ] }, "url": { "type": "string", "format": "uri", "description": "The https URL Klantly sends events to. No internal addresses, and only port 443, 80 or 8443.", "examples": [ "https://example.com/webhooks/klantly" ] }, "description": { "type": [ "string", "null" ], "description": "Your own description, for example what the endpoint is for.", "examples": [ "Boekhouding" ] }, "events": { "type": "array", "items": { "type": "string" }, "description": "The event types this endpoint receives, or [\"*\"] for every event the key or user can read.", "examples": [ [ "customer.created", "deal.won" ] ] }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "active or disabled.", "examples": [ "active" ] }, "disabled_reason": { "type": [ "string", "null" ], "enum": [ "failing", "manual", null, null ], "description": "Why the endpoint is off: failing (only errors for 5 days) or manual, otherwise null.", "examples": [ null ] }, "disabled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the endpoint was disabled.", "examples": [ null ] }, "previous_secret_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Until when the previous secret is still used after a rotation, otherwise null.", "examples": [ null ] }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Last successful delivery.", "examples": [ "2026-09-14T10:15:02Z" ] }, "last_failure_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Last failed delivery.", "examples": [ null ] }, "created_at": { "type": "string", "format": "date-time", "description": "Created at (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Last updated at (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": "Always \"webhook_endpoint\".", "examples": [ "webhook_endpoint" ] }, "id": { "type": "string", "description": "Id of the endpoint.", "examples": [ "01j7zr8m2k4n6p8r0t2v4w6y8a" ] }, "url": { "type": "string", "format": "uri", "description": "The https URL Klantly sends events to. No internal addresses, and only port 443, 80 or 8443.", "examples": [ "https://example.com/webhooks/klantly" ] }, "description": { "type": [ "string", "null" ], "description": "Your own description, for example what the endpoint is for.", "examples": [ "Boekhouding" ] }, "events": { "type": "array", "items": { "type": "string" }, "description": "The event types this endpoint receives, or [\"*\"] for every event the key or user can read.", "examples": [ [ "customer.created", "deal.won" ] ] }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "active or disabled.", "examples": [ "active" ] }, "disabled_reason": { "type": [ "string", "null" ], "enum": [ "failing", "manual", null, null ], "description": "Why the endpoint is off: failing (only errors for 5 days) or manual, otherwise null.", "examples": [ null ] }, "disabled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the endpoint was disabled.", "examples": [ null ] }, "previous_secret_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Until when the previous secret is still used after a rotation, otherwise null.", "examples": [ null ] }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Last successful delivery.", "examples": [ "2026-09-14T10:15:02Z" ] }, "last_failure_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Last failed delivery.", "examples": [ null ] }, "created_at": { "type": "string", "format": "date-time", "description": "Created at (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Last updated at (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "secret": { "type": "string", "pattern": "^whsec_", "description": "The secret (whsec_…) for checking signatures. Only in this response: store it right away.", "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": "Always \"webhook_delivery\".", "examples": [ "webhook_delivery" ] }, "id": { "type": "string", "description": "Id of the delivery attempt.", "examples": [ "1834" ] }, "webhook_endpoint_id": { "type": "string", "description": "The endpoint.", "examples": [ "01j7zr8m2k4n6p8r0t2v4w6y8a" ] }, "event_id": { "type": "string", "description": "The event that was sent.", "examples": [ "evt_01j7zs1a2b3c4d5e6f7g8h9j0k" ] }, "event_type": { "type": "string", "description": "The event type; ping for a test.", "examples": [ "ping" ] }, "attempt": { "type": "integer", "description": "Attempt number (1 is the first).", "examples": [ 1 ] }, "status": { "type": "string", "enum": [ "succeeded", "failed" ], "description": "succeeded (2xx response) or failed.", "examples": [ "succeeded" ] }, "response_status": { "type": [ "integer", "null" ], "description": "HTTP status from your server, or null if no response came.", "examples": [ 200 ] }, "error": { "type": [ "string", "null" ], "description": "What went wrong when no response came, for example connection_failed, otherwise null.", "examples": [ null ] }, "duration_ms": { "type": "integer", "description": "How long the attempt took, in milliseconds.", "examples": [ 184 ] }, "created_at": { "type": "string", "format": "date-time", "description": "Time of the attempt (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": "Always \"event\".", "examples": [ "event" ] }, "id": { "type": "string", "pattern": "^evt_", "description": "Unique id (evt_…). Same as the webhook-id header: use it to recognise duplicate messages.", "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": "The kind of event, for example customer.created.", "examples": [ "customer.created" ] }, "created_at": { "type": "string", "format": "date-time", "description": "When it happened (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "data": { "description": "The content of the event.", "type": "object", "required": [ "object" ], "properties": { "object": { "type": "object", "description": "The object as it was after the change, in the same shape as in the REST API (for note.deleted: as it was before deletion).", "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": "The kind of object that was deleted, for example \"note\".", "examples": [ "note" ] }, "id": { "type": "string", "description": "Id of the deleted object.", "examples": [ "9d3f7b41-2d6f-4e8c-9b3a-4f5d6e7a8b92" ] }, "deleted": { "type": "boolean", "const": true, "description": "Always true.", "examples": [ true ] } }, "additionalProperties": false }, "CustomersCreateRequest": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 255, "x-unique": true, "description": "Email address; unique within your company." }, "type": { "type": "string", "enum": [ "individual", "business" ], "description": "individual or business." }, "name": { "type": [ "string", "null" ], "maxLength": 255, "description": "Name of the contact person." }, "phone": { "type": [ "string", "null" ], "maxLength": 255, "description": "Phone number." }, "address": { "type": [ "string", "null" ], "maxLength": 255, "description": "Street and house number." }, "city": { "type": [ "string", "null" ], "maxLength": 255, "description": "City." }, "postal_code": { "type": [ "string", "null" ], "maxLength": 64, "description": "Postal code." }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "minLength": 2, "maxLength": 2, "description": "Country." }, "company_name": { "type": [ "string", "null" ], "maxLength": 255, "description": "Company name, for a business customer." }, "vat_number": { "type": [ "string", "null" ], "maxLength": 20, "description": "VAT number." }, "coc_number": { "type": [ "string", "null" ], "maxLength": 30, "description": "Chamber of Commerce number." } }, "additionalProperties": false }, "CustomersUpdateRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 255, "x-unique": true, "description": "Email address; unique within your company." }, "type": { "type": "string", "enum": [ "individual", "business" ], "description": "individual or business." }, "name": { "type": [ "string", "null" ], "maxLength": 255, "description": "Name of the contact person." }, "phone": { "type": [ "string", "null" ], "maxLength": 255, "description": "Phone number." }, "address": { "type": [ "string", "null" ], "maxLength": 255, "description": "Street and house number." }, "city": { "type": [ "string", "null" ], "maxLength": 255, "description": "City." }, "postal_code": { "type": [ "string", "null" ], "maxLength": 64, "description": "Postal code." }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "minLength": 2, "maxLength": 2, "description": "Country." }, "company_name": { "type": [ "string", "null" ], "maxLength": 255, "description": "Company name, for a business customer." }, "vat_number": { "type": [ "string", "null" ], "maxLength": 20, "description": "VAT number." }, "coc_number": { "type": [ "string", "null" ], "maxLength": 30, "description": "Chamber of Commerce number." } }, "additionalProperties": false }, "NotesCreateCustomerRequest": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "maxLength": 10000, "description": "The text of the note." }, "is_important": { "type": "boolean", "description": "Marked as important." } }, "additionalProperties": false }, "NotesUpdateCustomerRequest": { "type": "object", "properties": { "content": { "type": "string", "maxLength": 10000, "description": "The text of the note." }, "is_important": { "type": "boolean", "description": "Marked as important." } }, "additionalProperties": false }, "NotesCreateDealRequest": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "maxLength": 10000, "description": "The text of the note." }, "is_important": { "type": "boolean", "description": "Marked as important." } }, "additionalProperties": false }, "NotesUpdateDealRequest": { "type": "object", "properties": { "content": { "type": "string", "maxLength": 10000, "description": "The text of the note." }, "is_important": { "type": "boolean", "description": "Marked as important." } }, "additionalProperties": false }, "DealsCreateRequest": { "type": "object", "required": [ "customer_id" ], "properties": { "customer_id": { "type": "string", "format": "uuid", "description": "The customer of the deal." }, "title": { "type": [ "string", "null" ], "maxLength": 255, "description": "Title of the deal." }, "description": { "type": [ "string", "null" ], "maxLength": 10000, "description": "Description." }, "value": { "type": [ "number", "null" ], "minimum": 0, "maximum": 99999999, "multipleOf": 0.01, "description": "Value as a string with two decimals, for example \"8450.00\". When creating or updating you may also send a number." }, "stage_id": { "type": [ "integer", "null" ], "description": "The stage the deal goes into. Without stage_id: the default stage." }, "assigned_user_id": { "type": [ "integer", "null" ], "description": "The user handling the deal, or null." } }, "additionalProperties": false }, "DealsUpdateRequest": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 255, "description": "Title of the deal." }, "description": { "type": [ "string", "null" ], "maxLength": 10000, "description": "Description." }, "value": { "type": "number", "minimum": 0, "maximum": 99999999, "multipleOf": 0.01, "description": "Value as a string with two decimals, for example \"8450.00\". When creating or updating you may also send a number." }, "assigned_user_id": { "type": [ "integer", "null" ], "description": "The user handling the deal, or null." } }, "additionalProperties": false }, "DealsMoveRequest": { "type": "object", "required": [ "stage_id" ], "properties": { "stage_id": { "type": "integer", "description": "The id of the stage the deal moves to (from List pipeline stages)." }, "notes": { "type": [ "string", "null" ], "maxLength": 500, "description": "Optional note; kept in the history of the deal together with the stage change." } }, "additionalProperties": false }, "DealsLoseRequest": { "type": "object", "properties": { "lost_reason": { "type": [ "string", "null" ], "maxLength": 255, "description": "Why the deal was lost, or null." } }, "additionalProperties": false }, "WebhookEndpointsCreateRequest": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "The https URL Klantly sends events to. No internal addresses, and only port 443, 80 or 8443." }, "description": { "type": [ "string", "null" ], "maxLength": 255, "description": "Your own description, for example what the endpoint is for." }, "events": { "type": "array", "minItems": 1, "maxItems": 50, "description": "The event types this endpoint receives, or [\"*\"] for every event the key or user can read." } }, "additionalProperties": false }, "WebhookEndpointsUpdateRequest": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "The https URL Klantly sends events to. No internal addresses, and only port 443, 80 or 8443." }, "description": { "type": [ "string", "null" ], "maxLength": 255, "description": "Your own description, for example what the endpoint is for." }, "events": { "type": "array", "minItems": 1, "maxItems": 50, "description": "The event types this endpoint receives, or [\"*\"] for every event the key or user can read." }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "active or disabled." } }, "additionalProperties": false }, "WebhookEndpointsRotateSecretRequest": { "type": "object", "properties": { "overlap_hours": { "type": "integer", "enum": [ "0", "1", "24", "168" ], "description": "How long the old secret keeps working next to the new one: 0, 1, 24 (default) or 168 hours." } }, "additionalProperties": false } } } }