{ "openapi": "3.1.0", "info": { "title": "Klantly API", "version": "1.0.0", "description": "Die öffentliche API von Klantly. Authentifizieren Sie sich mit einem API-Schlüssel als Bearer-Token. Anleitungen, Fehlercodes und Beispiele finden Sie im Entwicklerportal.", "contact": { "name": "Klantly", "url": "https://developers.klantly.com/de/support" } }, "externalDocs": { "url": "https://developers.klantly.com/de", "description": "Klantly Developers" }, "servers": [ { "url": "https://app.klantly.com/api/v1" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "API-Schlüssel", "description": "Testen Sie Ihre Verbindung und sehen Sie, welcher Schlüssel, welches Unternehmen, welche Scopes und welche Limits gelten." }, { "name": "Unternehmen", "description": "Die Daten Ihres eigenen Unternehmens: Name, Adresse, Sprache und Umsatzsteuer-Einstellungen." }, { "name": "Benutzer", "description": "Die Benutzer Ihres Unternehmens, zum Beispiel um einen Deal jemandem zuzuweisen." }, { "name": "Kunden", "description": "Kunden und Leads: erstellen, suchen, bearbeiten und einen Lead in einen Kunden umwandeln." }, { "name": "Notizen", "description": "Interne Notizen zu einem Kunden oder Deal. Ihr Kunde sieht sie nie." }, { "name": "Pipeline-Phasen", "description": "Die Phasen Ihres Pipeline-Boards, in ihrer Reihenfolge, und ob eine Phase offen, gewonnen oder verloren bedeutet." }, { "name": "Deals", "description": "Die Karten auf Ihrem Pipeline-Board: erstellen, bearbeiten, in eine andere Phase verschieben, gewinnen, verlieren und archivieren." }, { "name": "Webhook-Endpunkte", "description": "Adressen, an die Klantly sofort eine Nachricht sendet, sobald sich etwas ändert. Signaturen und Wiederholungen erklärt der Leitfaden zu Webhooks." }, { "name": "Events", "description": "Alles, was sich in den letzten 30 Tagen geändert hat, als Liste. Um verpasste Webhooks nachzuholen oder um abzufragen, statt Webhooks zu verwenden." } ], "paths": { "/me": { "get": { "operationId": "me", "summary": "Schlüssel und Unternehmen abrufen", "description": "Gibt den Schlüssel zurück, mit dem Sie die Anfrage stellen, samt Unternehmen, Scopes, Ablaufdatum und Limits. Nutzen Sie diesen Endpunkt, um Ihre Verbindung zu testen: Er erfordert keinen Scope.", "tags": [ "API-Schlüssel" ], "x-klantly-scope": null, "externalDocs": { "url": "https://developers.klantly.com/de/reference/api-key#me" }, "responses": { "200": { "description": "Erfolgreich", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "schema": { "type": "string" } }, "ETag": { "description": "Version des Objekts, für 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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/company": { "get": { "operationId": "companyGet", "summary": "Unternehmen abrufen", "description": "Die Daten des Unternehmens, zu dem der Schlüssel gehört, mit dem Standard-Steuersatz und ob Preise inklusive Umsatzsteuer sind.", "tags": [ "Unternehmen" ], "x-klantly-scope": "company.read", "externalDocs": { "url": "https://developers.klantly.com/de/reference/company#companyget" }, "responses": { "200": { "description": "Erfolgreich", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "schema": { "type": "string" } }, "ETag": { "description": "Version des Objekts, für 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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "status": 403, "code": "insufficient_scope", "detail": "Dafür ist der Scope customers.write erforderlich. Passen Sie die Scopes des Schlüssels in Klantly an.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/users": { "get": { "operationId": "usersList", "summary": "Benutzer auflisten", "description": "Die Benutzer Ihres Unternehmens, nach ID sortiert. Verwenden Sie die ID als assigned_user_id eines Deals.", "tags": [ "Benutzer" ], "x-klantly-scope": "users.read", "externalDocs": { "url": "https://developers.klantly.com/de/reference/users#userslist" }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Anzahl der Ergebnisse pro Seite.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Der next_cursor oder prev_cursor aus meta der vorherigen Antwort.", "schema": { "type": "string" } }, { "name": "filter[status]", "in": "query", "required": false, "description": "Nur aktive oder nur deaktivierte Benutzer.", "schema": { "type": "string", "enum": [ "active", "inactive" ] } } ], "responses": { "200": { "description": "Erfolgreich", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "status": 403, "code": "insufficient_scope", "detail": "Dafür ist der Scope customers.write erforderlich. Passen Sie die Scopes des Schlüssels in Klantly an.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Die Eingabe ist ungültig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Die Eingabe ist ungültig.", "status": 422, "code": "validation_failed", "detail": "1 Feld ist ungültig.", "errors": { "email": [ "Email muss eine gültige E-Mail-Adresse sein." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/customers": { "get": { "operationId": "customersList", "summary": "Kunden auflisten", "description": "Eine Liste von Kunden und Leads, die neuesten zuerst. Filtern Sie nach Status, Typ, E-Mail-Adresse oder Änderungsdatum, suchen Sie mit q und blättern Sie mit dem Cursor aus meta.", "tags": [ "Kunden" ], "x-klantly-scope": "customers.read", "externalDocs": { "url": "https://developers.klantly.com/de/reference/customers#customerslist" }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Anzahl der Ergebnisse pro Seite.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Der next_cursor oder prev_cursor aus meta der vorherigen Antwort.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Suche in Name, E-Mail-Adresse, Firmenname und Telefonnummer.", "schema": { "type": "string", "minLength": 2, "maxLength": 100 } }, { "name": "sort", "in": "query", "required": false, "description": "Sortierung nach created_at oder updated_at; ein Minuszeichen davor sortiert absteigend.", "schema": { "type": "string", "enum": [ "-created_at", "created_at", "-updated_at", "updated_at" ], "default": "-created_at" } }, { "name": "filter[status]", "in": "query", "required": false, "description": "Nur Leads oder nur Kunden.", "schema": { "type": "string", "enum": [ "lead", "customer" ] } }, { "name": "filter[type]", "in": "query", "required": false, "description": "Nur Privatpersonen oder nur Unternehmen.", "schema": { "type": "string", "enum": [ "individual", "business" ] } }, { "name": "filter[email]", "in": "query", "required": false, "description": "Genau diese E-Mail-Adresse (ohne Beachtung der Groß- und Kleinschreibung).", "schema": { "type": "string", "format": "email" } }, { "name": "filter[updated_since]", "in": "query", "required": false, "description": "Nur was seit diesem Zeitpunkt geändert wurde: ISO 8601 mit Zeitzone, zum Beispiel 2026-09-14T10:15:00Z. Praktisch zum Synchronisieren.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Erfolgreich", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "status": 403, "code": "insufficient_scope", "detail": "Dafür ist der Scope customers.write erforderlich. Passen Sie die Scopes des Schlüssels in Klantly an.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Die Eingabe ist ungültig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Die Eingabe ist ungültig.", "status": 422, "code": "validation_failed", "detail": "1 Feld ist ungültig.", "errors": { "email": [ "Email muss eine gültige E-Mail-Adresse sein." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "post": { "operationId": "customersCreate", "summary": "Kunden erstellen", "description": "Erstellt einen neuen Lead. Die E-Mail-Adresse ist erforderlich und innerhalb Ihres Unternehmens eindeutig: Eine vorhandene Adresse ergibt einen Validierungsfehler. Automationen und die Kundenhistorie funktionieren genau wie beim Erstellen in Klantly selbst.", "tags": [ "Kunden" ], "x-klantly-scope": "customers.write", "externalDocs": { "url": "https://developers.klantly.com/de/reference/customers#customerscreate" }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Ein eindeutiger Schlüssel pro Anfrage (zum Beispiel eine UUID): Ein erneuter Versuch erzeugt dann keinen doppelten Datensatz. 24 Stunden gültig.", "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": "Erstellt", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "schema": { "type": "string" } }, "ETag": { "description": "Version des Objekts, für 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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "status": 403, "code": "insufficient_scope", "detail": "Dafür ist der Scope customers.write erforderlich. Passen Sie die Scopes des Schlüssels in Klantly an.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "limit_reached": { "summary": "Das Limit des Abonnements ist erreicht.", "value": { "type": "https://developers.klantly.com/errors/limit_reached", "title": "Das Limit des Abonnements ist erreicht.", "status": 403, "code": "limit_reached", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Eine Anfrage mit diesem Idempotency-Key wird noch verarbeitet.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Eine Anfrage mit diesem Idempotency-Key wird noch verarbeitet.", "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": "Der Body der Anfrage ist zu groß.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "Der Body der Anfrage ist zu groß.", "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": "Dieses Format wird nicht unterstützt.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Dieses Format wird nicht unterstützt.", "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": "Die Eingabe ist ungültig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Die Eingabe ist ungültig.", "status": 422, "code": "validation_failed", "detail": "1 Feld ist ungültig.", "errors": { "email": [ "Email muss eine gültige E-Mail-Adresse sein." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "Die Eingabe enthält ein unbekanntes Feld.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "Die Eingabe enthält ein unbekanntes Feld.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_key_reused": { "summary": "Dieser Idempotency-Key wurde bereits für eine andere Anfrage verwendet.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Dieser Idempotency-Key wurde bereits für eine andere Anfrage verwendet.", "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": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/customers/{customer}": { "get": { "operationId": "customersGet", "summary": "Kunden abrufen", "description": "Ein einzelner Kunde anhand der ID. Die Antwort enthält ein ETag, das Sie beim Bearbeiten in If-Match mitsenden können.", "tags": [ "Kunden" ], "x-klantly-scope": "customers.read", "externalDocs": { "url": "https://developers.klantly.com/de/reference/customers#customersget" }, "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "Die ID (UUID) des Kunden.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Erfolgreich", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "schema": { "type": "string" } }, "ETag": { "description": "Version des Objekts, für 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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "status": 403, "code": "insufficient_scope", "detail": "Dafür ist der Scope customers.write erforderlich. Passen Sie die Scopes des Schlüssels in Klantly an.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Nicht gefunden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Nicht gefunden.", "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": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "patch": { "operationId": "customersUpdate", "summary": "Kunden bearbeiten", "description": "Ändert nur die Felder, die Sie mitsenden. Der Status ändert sich über diesen Endpunkt nicht; verwenden Sie dafür „Lead in Kunden umwandeln“.", "tags": [ "Kunden" ], "x-klantly-scope": "customers.write", "externalDocs": { "url": "https://developers.klantly.com/de/reference/customers#customersupdate" }, "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "Die ID (UUID) des Kunden.", "schema": { "type": "string", "format": "uuid" } }, { "name": "If-Match", "in": "header", "required": false, "description": "Das ETag der abgerufenen Version. Wurde der Datensatz inzwischen geändert, folgt 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": "Erfolgreich", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "schema": { "type": "string" } }, "ETag": { "description": "Version des Objekts, für 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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "status": 403, "code": "insufficient_scope", "detail": "Dafür ist der Scope customers.write erforderlich. Passen Sie die Scopes des Schlüssels in Klantly an.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Nicht gefunden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Nicht gefunden.", "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": "Der Datensatz wurde inzwischen geändert.", "value": { "type": "https://developers.klantly.com/errors/precondition_failed", "title": "Der Datensatz wurde inzwischen geändert.", "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": "Der Body der Anfrage ist zu groß.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "Der Body der Anfrage ist zu groß.", "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": "Dieses Format wird nicht unterstützt.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Dieses Format wird nicht unterstützt.", "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": "Die Eingabe ist ungültig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Die Eingabe ist ungültig.", "status": 422, "code": "validation_failed", "detail": "1 Feld ist ungültig.", "errors": { "email": [ "Email muss eine gültige E-Mail-Adresse sein." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "Die Eingabe enthält ein unbekanntes Feld.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "Die Eingabe enthält ein unbekanntes Feld.", "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": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/customers/{customer}/convert": { "post": { "operationId": "customersConvert", "summary": "Lead in Kunden umwandeln", "description": "Wandelt einen Lead in einen Kunden um. Ist es bereits ein Kunde, ändert sich nichts und Sie erhalten den Kunden einfach zurück.", "tags": [ "Kunden" ], "x-klantly-scope": "customers.write", "externalDocs": { "url": "https://developers.klantly.com/de/reference/customers#customersconvert" }, "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "Die ID (UUID) des Kunden.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Ein eindeutiger Schlüssel pro Anfrage (zum Beispiel eine UUID): Ein erneuter Versuch erzeugt dann keinen doppelten Datensatz. 24 Stunden gültig.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Erfolgreich", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "schema": { "type": "string" } }, "ETag": { "description": "Version des Objekts, für 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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "status": 403, "code": "insufficient_scope", "detail": "Dafür ist der Scope customers.write erforderlich. Passen Sie die Scopes des Schlüssels in Klantly an.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Nicht gefunden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Nicht gefunden.", "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": "Eine Anfrage mit diesem Idempotency-Key wird noch verarbeitet.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Eine Anfrage mit diesem Idempotency-Key wird noch verarbeitet.", "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": "Dieser Idempotency-Key wurde bereits für eine andere Anfrage verwendet.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Dieser Idempotency-Key wurde bereits für eine andere Anfrage verwendet.", "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": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/customers/{customer}/activities": { "get": { "operationId": "customersActivities", "summary": "Zeitleiste eines Kunden", "description": "Die Zeitleiste eines Kunden, neueste zuerst: Angebote, Rechnungen, Termine, E-Mails und mehr. Verweise auf verknüpfte Datensätze stehen unter related.", "tags": [ "Kunden" ], "x-klantly-scope": "customers.read", "externalDocs": { "url": "https://developers.klantly.com/de/reference/customers#customersactivities" }, "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "Die ID (UUID) des Kunden.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Anzahl der Ergebnisse pro Seite.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Der next_cursor oder prev_cursor aus meta der vorherigen Antwort.", "schema": { "type": "string" } }, { "name": "filter[type]", "in": "query", "required": false, "description": "Nur Aktivitäten dieses Typs, zum Beispiel quote_sent oder invoice_created.", "schema": { "type": "string", "maxLength": 40 } } ], "responses": { "200": { "description": "Erfolgreich", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "status": 403, "code": "insufficient_scope", "detail": "Dafür ist der Scope customers.write erforderlich. Passen Sie die Scopes des Schlüssels in Klantly an.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Nicht gefunden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Nicht gefunden.", "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": "Die Eingabe ist ungültig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Die Eingabe ist ungültig.", "status": 422, "code": "validation_failed", "detail": "1 Feld ist ungültig.", "errors": { "email": [ "Email muss eine gültige E-Mail-Adresse sein." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/customers/{customer}/notes": { "get": { "operationId": "notesListCustomer", "summary": "Notizen eines Kunden auflisten", "description": "Die Notizen zu einem Kunden, neueste zuerst.", "tags": [ "Notizen" ], "x-klantly-scope": "customers.read", "externalDocs": { "url": "https://developers.klantly.com/de/reference/notes#noteslist-customer" }, "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "Die ID (UUID) des Kunden.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Anzahl der Ergebnisse pro Seite.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Der next_cursor oder prev_cursor aus meta der vorherigen Antwort.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Erfolgreich", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "status": 403, "code": "insufficient_scope", "detail": "Dafür ist der Scope customers.write erforderlich. Passen Sie die Scopes des Schlüssels in Klantly an.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Nicht gefunden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Nicht gefunden.", "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": "Die Eingabe ist ungültig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Die Eingabe ist ungültig.", "status": 422, "code": "validation_failed", "detail": "1 Feld ist ungültig.", "errors": { "email": [ "Email muss eine gültige E-Mail-Adresse sein." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "post": { "operationId": "notesCreateCustomer", "summary": "Notiz zu einem Kunden hinzufügen", "description": "Fügt einem Kunden eine interne Notiz hinzu. Sie erscheint sofort in Klantly. Eine Notiz über die API hat keinen Autor.", "tags": [ "Notizen" ], "x-klantly-scope": "customers.write", "externalDocs": { "url": "https://developers.klantly.com/de/reference/notes#notescreate-customer" }, "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "Die ID (UUID) des Kunden.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Ein eindeutiger Schlüssel pro Anfrage (zum Beispiel eine UUID): Ein erneuter Versuch erzeugt dann keinen doppelten Datensatz. 24 Stunden gültig.", "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": "Erstellt", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "schema": { "type": "string" } }, "ETag": { "description": "Version des Objekts, für 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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "status": 403, "code": "insufficient_scope", "detail": "Dafür ist der Scope customers.write erforderlich. Passen Sie die Scopes des Schlüssels in Klantly an.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Nicht gefunden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Nicht gefunden.", "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": "Eine Anfrage mit diesem Idempotency-Key wird noch verarbeitet.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Eine Anfrage mit diesem Idempotency-Key wird noch verarbeitet.", "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": "Der Body der Anfrage ist zu groß.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "Der Body der Anfrage ist zu groß.", "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": "Dieses Format wird nicht unterstützt.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Dieses Format wird nicht unterstützt.", "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": "Die Eingabe ist ungültig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Die Eingabe ist ungültig.", "status": 422, "code": "validation_failed", "detail": "1 Feld ist ungültig.", "errors": { "email": [ "Email muss eine gültige E-Mail-Adresse sein." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "Die Eingabe enthält ein unbekanntes Feld.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "Die Eingabe enthält ein unbekanntes Feld.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_key_reused": { "summary": "Dieser Idempotency-Key wurde bereits für eine andere Anfrage verwendet.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Dieser Idempotency-Key wurde bereits für eine andere Anfrage verwendet.", "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": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/customers/{customer}/notes/{note}": { "patch": { "operationId": "notesUpdateCustomer", "summary": "Notiz eines Kunden bearbeiten", "description": "Ändert nur die Felder, die Sie mitsenden.", "tags": [ "Notizen" ], "x-klantly-scope": "customers.write", "externalDocs": { "url": "https://developers.klantly.com/de/reference/notes#notesupdate-customer" }, "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "Die ID (UUID) des Kunden.", "schema": { "type": "string", "format": "uuid" } }, { "name": "note", "in": "path", "required": true, "description": "Die ID (UUID) der Notiz.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotesUpdateCustomerRequest" }, "example": { "is_important": false } } } }, "responses": { "200": { "description": "Erfolgreich", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "schema": { "type": "string" } }, "ETag": { "description": "Version des Objekts, für 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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "status": 403, "code": "insufficient_scope", "detail": "Dafür ist der Scope customers.write erforderlich. Passen Sie die Scopes des Schlüssels in Klantly an.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Nicht gefunden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Nicht gefunden.", "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": "Der Body der Anfrage ist zu groß.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "Der Body der Anfrage ist zu groß.", "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": "Dieses Format wird nicht unterstützt.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Dieses Format wird nicht unterstützt.", "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": "Die Eingabe ist ungültig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Die Eingabe ist ungültig.", "status": 422, "code": "validation_failed", "detail": "1 Feld ist ungültig.", "errors": { "email": [ "Email muss eine gültige E-Mail-Adresse sein." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "Die Eingabe enthält ein unbekanntes Feld.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "Die Eingabe enthält ein unbekanntes Feld.", "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": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "delete": { "operationId": "notesDeleteCustomer", "summary": "Notiz eines Kunden löschen", "description": "Löscht die Notiz und ihre Anhänge. Das lässt sich nicht rückgängig machen.", "tags": [ "Notizen" ], "x-klantly-scope": "customers.write", "externalDocs": { "url": "https://developers.klantly.com/de/reference/notes#notesdelete-customer" }, "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "Die ID (UUID) des Kunden.", "schema": { "type": "string", "format": "uuid" } }, { "name": "note", "in": "path", "required": true, "description": "Die ID (UUID) der Notiz.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Erfolgreich", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "schema": { "type": "string" } }, "ETag": { "description": "Version des Objekts, für 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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "status": 403, "code": "insufficient_scope", "detail": "Dafür ist der Scope customers.write erforderlich. Passen Sie die Scopes des Schlüssels in Klantly an.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Nicht gefunden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Nicht gefunden.", "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": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals/{deal}/notes": { "get": { "operationId": "notesListDeal", "summary": "Notizen eines Deals auflisten", "description": "Die Notizen zu einem Deal, neueste zuerst.", "tags": [ "Notizen" ], "x-klantly-scope": "deals.read", "externalDocs": { "url": "https://developers.klantly.com/de/reference/notes#noteslist-deal" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "Die ID (UUID) des Deals.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Anzahl der Ergebnisse pro Seite.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Der next_cursor oder prev_cursor aus meta der vorherigen Antwort.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Erfolgreich", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "status": 403, "code": "insufficient_scope", "detail": "Dafür ist der Scope customers.write erforderlich. Passen Sie die Scopes des Schlüssels in Klantly an.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Nicht gefunden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Nicht gefunden.", "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": "Die Eingabe ist ungültig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Die Eingabe ist ungültig.", "status": 422, "code": "validation_failed", "detail": "1 Feld ist ungültig.", "errors": { "email": [ "Email muss eine gültige E-Mail-Adresse sein." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "post": { "operationId": "notesCreateDeal", "summary": "Notiz zu einem Deal hinzufügen", "description": "Fügt einem Deal eine interne Notiz hinzu. Sie erscheint sofort in Klantly. Eine Notiz über die API hat keinen Autor.", "tags": [ "Notizen" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/de/reference/notes#notescreate-deal" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "Die ID (UUID) des Deals.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Ein eindeutiger Schlüssel pro Anfrage (zum Beispiel eine UUID): Ein erneuter Versuch erzeugt dann keinen doppelten Datensatz. 24 Stunden gültig.", "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": "Erstellt", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "schema": { "type": "string" } }, "ETag": { "description": "Version des Objekts, für 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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "status": 403, "code": "insufficient_scope", "detail": "Dafür ist der Scope customers.write erforderlich. Passen Sie die Scopes des Schlüssels in Klantly an.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Nicht gefunden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Nicht gefunden.", "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": "Eine Anfrage mit diesem Idempotency-Key wird noch verarbeitet.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Eine Anfrage mit diesem Idempotency-Key wird noch verarbeitet.", "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": "Der Body der Anfrage ist zu groß.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "Der Body der Anfrage ist zu groß.", "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": "Dieses Format wird nicht unterstützt.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Dieses Format wird nicht unterstützt.", "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": "Die Eingabe ist ungültig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Die Eingabe ist ungültig.", "status": 422, "code": "validation_failed", "detail": "1 Feld ist ungültig.", "errors": { "email": [ "Email muss eine gültige E-Mail-Adresse sein." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "Die Eingabe enthält ein unbekanntes Feld.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "Die Eingabe enthält ein unbekanntes Feld.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_key_reused": { "summary": "Dieser Idempotency-Key wurde bereits für eine andere Anfrage verwendet.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Dieser Idempotency-Key wurde bereits für eine andere Anfrage verwendet.", "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": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals/{deal}/notes/{note}": { "patch": { "operationId": "notesUpdateDeal", "summary": "Notiz eines Deals bearbeiten", "description": "Ändert nur die Felder, die Sie mitsenden.", "tags": [ "Notizen" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/de/reference/notes#notesupdate-deal" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "Die ID (UUID) des Deals.", "schema": { "type": "string", "format": "uuid" } }, { "name": "note", "in": "path", "required": true, "description": "Die ID (UUID) der Notiz.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotesUpdateDealRequest" }, "example": { "is_important": false } } } }, "responses": { "200": { "description": "Erfolgreich", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "schema": { "type": "string" } }, "ETag": { "description": "Version des Objekts, für 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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "status": 403, "code": "insufficient_scope", "detail": "Dafür ist der Scope customers.write erforderlich. Passen Sie die Scopes des Schlüssels in Klantly an.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Nicht gefunden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Nicht gefunden.", "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": "Der Body der Anfrage ist zu groß.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "Der Body der Anfrage ist zu groß.", "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": "Dieses Format wird nicht unterstützt.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Dieses Format wird nicht unterstützt.", "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": "Die Eingabe ist ungültig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Die Eingabe ist ungültig.", "status": 422, "code": "validation_failed", "detail": "1 Feld ist ungültig.", "errors": { "email": [ "Email muss eine gültige E-Mail-Adresse sein." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "Die Eingabe enthält ein unbekanntes Feld.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "Die Eingabe enthält ein unbekanntes Feld.", "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": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "delete": { "operationId": "notesDeleteDeal", "summary": "Notiz eines Deals löschen", "description": "Löscht die Notiz und ihre Anhänge. Das lässt sich nicht rückgängig machen.", "tags": [ "Notizen" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/de/reference/notes#notesdelete-deal" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "Die ID (UUID) des Deals.", "schema": { "type": "string", "format": "uuid" } }, { "name": "note", "in": "path", "required": true, "description": "Die ID (UUID) der Notiz.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Erfolgreich", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "schema": { "type": "string" } }, "ETag": { "description": "Version des Objekts, für 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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "status": 403, "code": "insufficient_scope", "detail": "Dafür ist der Scope customers.write erforderlich. Passen Sie die Scopes des Schlüssels in Klantly an.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Nicht gefunden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Nicht gefunden.", "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": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/pipeline-stages": { "get": { "operationId": "pipelineStagesList", "summary": "Pipeline-Phasen auflisten", "description": "Alle aktiven Phasen des Pipeline-Boards, in der Reihenfolge des Boards. Die Namen in allen vier Sprachen stehen unter names.", "tags": [ "Pipeline-Phasen" ], "x-klantly-scope": "deals.read", "externalDocs": { "url": "https://developers.klantly.com/de/reference/pipeline-stages#pipeline-stageslist" }, "responses": { "200": { "description": "Erfolgreich", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "status": 403, "code": "insufficient_scope", "detail": "Dafür ist der Scope customers.write erforderlich. Passen Sie die Scopes des Schlüssels in Klantly an.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals": { "get": { "operationId": "dealsList", "summary": "Deals auflisten", "description": "Eine Liste von Deals, neueste zuerst. Archivierte Deals sind standardmäßig nicht enthalten; verwenden Sie dafür filter[archived]. Filtern Sie nach Status, Phase, Kunde, Verantwortlichem oder Änderungsdatum.", "tags": [ "Deals" ], "x-klantly-scope": "deals.read", "externalDocs": { "url": "https://developers.klantly.com/de/reference/deals#dealslist" }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Anzahl der Ergebnisse pro Seite.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Der next_cursor oder prev_cursor aus meta der vorherigen Antwort.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sortierung nach created_at, updated_at oder stage_changed_at; ein Minuszeichen davor bedeutet absteigend.", "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": "Nur offene, gewonnene oder verlorene Deals.", "schema": { "type": "string", "enum": [ "open", "won", "lost" ] } }, { "name": "filter[stage_id]", "in": "query", "required": false, "description": "Nur Deals in dieser Phase (die ID aus Pipeline-Phasen auflisten).", "schema": { "type": "integer" } }, { "name": "filter[customer_id]", "in": "query", "required": false, "description": "Nur Deals dieses Kunden.", "schema": { "type": "string", "format": "uuid" } }, { "name": "filter[assigned_user_id]", "in": "query", "required": false, "description": "Nur Deals dieses Benutzers.", "schema": { "type": "integer" } }, { "name": "filter[archived]", "in": "query", "required": false, "description": "false (Standard) zeigt nur Deals auf dem Board, true nur archivierte, all beide.", "schema": { "type": "string", "enum": [ "false", "true", "all" ], "default": "false" } }, { "name": "filter[updated_since]", "in": "query", "required": false, "description": "Nur was seit diesem Zeitpunkt geändert wurde: ISO 8601 mit Zeitzone, zum Beispiel 2026-09-14T10:15:00Z. Praktisch zum Synchronisieren.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Erfolgreich", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "status": 403, "code": "insufficient_scope", "detail": "Dafür ist der Scope customers.write erforderlich. Passen Sie die Scopes des Schlüssels in Klantly an.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Die Eingabe ist ungültig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Die Eingabe ist ungültig.", "status": 422, "code": "validation_failed", "detail": "1 Feld ist ungültig.", "errors": { "email": [ "Email muss eine gültige E-Mail-Adresse sein." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "post": { "operationId": "dealsCreate", "summary": "Deal erstellen", "description": "Setzt einen Kunden auf das Pipeline-Board. Ein Kunde kann nur einen offenen Deal gleichzeitig haben: Gibt es schon einen, folgt 409 mit dessen ID in deal_id. Ohne stage_id landet der Deal in der Standardphase. Senden Sie value mit, behält Klantly diesen Betrag bei, statt ihn aus den Angeboten zu berechnen.", "tags": [ "Deals" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/de/reference/deals#dealscreate" }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Ein eindeutiger Schlüssel pro Anfrage (zum Beispiel eine UUID): Ein erneuter Versuch erzeugt dann keinen doppelten Datensatz. 24 Stunden gültig.", "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": "Erstellt", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "schema": { "type": "string" } }, "ETag": { "description": "Version des Objekts, für 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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "status": 403, "code": "insufficient_scope", "detail": "Dafür ist der Scope customers.write erforderlich. Passen Sie die Scopes des Schlüssels in Klantly an.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Dies steht im Widerspruch zum aktuellen Zustand.", "value": { "type": "https://developers.klantly.com/errors/conflict", "title": "Dies steht im Widerspruch zum aktuellen Zustand.", "status": 409, "code": "conflict", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_in_progress": { "summary": "Eine Anfrage mit diesem Idempotency-Key wird noch verarbeitet.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Eine Anfrage mit diesem Idempotency-Key wird noch verarbeitet.", "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": "Der Body der Anfrage ist zu groß.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "Der Body der Anfrage ist zu groß.", "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": "Dieses Format wird nicht unterstützt.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Dieses Format wird nicht unterstützt.", "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": "Die Eingabe ist ungültig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Die Eingabe ist ungültig.", "status": 422, "code": "validation_failed", "detail": "1 Feld ist ungültig.", "errors": { "email": [ "Email muss eine gültige E-Mail-Adresse sein." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "Die Eingabe enthält ein unbekanntes Feld.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "Die Eingabe enthält ein unbekanntes Feld.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_key_reused": { "summary": "Dieser Idempotency-Key wurde bereits für eine andere Anfrage verwendet.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Dieser Idempotency-Key wurde bereits für eine andere Anfrage verwendet.", "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": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals/{deal}": { "get": { "operationId": "dealsGet", "summary": "Deal abrufen", "description": "Ein Deal nach ID. Die Antwort enthält einen ETag, den Sie beim Bearbeiten in If-Match mitsenden können.", "tags": [ "Deals" ], "x-klantly-scope": "deals.read", "externalDocs": { "url": "https://developers.klantly.com/de/reference/deals#dealsget" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "Die ID (UUID) des Deals.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Erfolgreich", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "schema": { "type": "string" } }, "ETag": { "description": "Version des Objekts, für 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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "status": 403, "code": "insufficient_scope", "detail": "Dafür ist der Scope customers.write erforderlich. Passen Sie die Scopes des Schlüssels in Klantly an.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Nicht gefunden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Nicht gefunden.", "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": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "patch": { "operationId": "dealsUpdate", "summary": "Deal bearbeiten", "description": "Ändert nur die Felder, die Sie mitsenden. Die Phase ändern Sie mit Verschieben, Gewinnen oder Verlieren. Ein mitgesendeter value setzt value_source auf manual.", "tags": [ "Deals" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/de/reference/deals#dealsupdate" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "Die ID (UUID) des Deals.", "schema": { "type": "string", "format": "uuid" } }, { "name": "If-Match", "in": "header", "required": false, "description": "Das ETag der abgerufenen Version. Wurde der Datensatz inzwischen geändert, folgt 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": "Erfolgreich", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "schema": { "type": "string" } }, "ETag": { "description": "Version des Objekts, für 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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "status": 403, "code": "insufficient_scope", "detail": "Dafür ist der Scope customers.write erforderlich. Passen Sie die Scopes des Schlüssels in Klantly an.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Nicht gefunden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Nicht gefunden.", "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": "Der Datensatz wurde inzwischen geändert.", "value": { "type": "https://developers.klantly.com/errors/precondition_failed", "title": "Der Datensatz wurde inzwischen geändert.", "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": "Der Body der Anfrage ist zu groß.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "Der Body der Anfrage ist zu groß.", "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": "Dieses Format wird nicht unterstützt.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Dieses Format wird nicht unterstützt.", "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": "Die Eingabe ist ungültig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Die Eingabe ist ungültig.", "status": 422, "code": "validation_failed", "detail": "1 Feld ist ungültig.", "errors": { "email": [ "Email muss eine gültige E-Mail-Adresse sein." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "Die Eingabe enthält ein unbekanntes Feld.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "Die Eingabe enthält ein unbekanntes Feld.", "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": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals/{deal}/move": { "post": { "operationId": "dealsMove", "summary": "Deal verschieben", "description": "Verschiebt den Deal in eine andere Phase, genau wie das Ziehen auf dem Board. Ist das eine gewonnene oder verlorene Phase, wird der Deal ebenfalls gewonnen oder verloren.", "tags": [ "Deals" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/de/reference/deals#dealsmove" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "Die ID (UUID) des Deals.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Ein eindeutiger Schlüssel pro Anfrage (zum Beispiel eine UUID): Ein erneuter Versuch erzeugt dann keinen doppelten Datensatz. 24 Stunden gültig.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealsMoveRequest" }, "example": { "stage_id": 3 } } } }, "responses": { "200": { "description": "Erfolgreich", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "schema": { "type": "string" } }, "ETag": { "description": "Version des Objekts, für 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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "status": 403, "code": "insufficient_scope", "detail": "Dafür ist der Scope customers.write erforderlich. Passen Sie die Scopes des Schlüssels in Klantly an.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Nicht gefunden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Nicht gefunden.", "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": "Eine Anfrage mit diesem Idempotency-Key wird noch verarbeitet.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Eine Anfrage mit diesem Idempotency-Key wird noch verarbeitet.", "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": "Der Body der Anfrage ist zu groß.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "Der Body der Anfrage ist zu groß.", "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": "Dieses Format wird nicht unterstützt.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Dieses Format wird nicht unterstützt.", "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": "Die Eingabe ist ungültig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Die Eingabe ist ungültig.", "status": 422, "code": "validation_failed", "detail": "1 Feld ist ungültig.", "errors": { "email": [ "Email muss eine gültige E-Mail-Adresse sein." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "Die Eingabe enthält ein unbekanntes Feld.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "Die Eingabe enthält ein unbekanntes Feld.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_key_reused": { "summary": "Dieser Idempotency-Key wurde bereits für eine andere Anfrage verwendet.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Dieser Idempotency-Key wurde bereits für eine andere Anfrage verwendet.", "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": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals/{deal}/win": { "post": { "operationId": "dealsWin", "summary": "Deal gewinnen", "description": "Verschiebt den Deal in die Phase, die Ihr Unternehmen als gewonnen eingerichtet hat. Ist er schon gewonnen, ändert sich nichts.", "tags": [ "Deals" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/de/reference/deals#dealswin" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "Die ID (UUID) des Deals.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Ein eindeutiger Schlüssel pro Anfrage (zum Beispiel eine UUID): Ein erneuter Versuch erzeugt dann keinen doppelten Datensatz. 24 Stunden gültig.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Erfolgreich", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "schema": { "type": "string" } }, "ETag": { "description": "Version des Objekts, für 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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "status": 403, "code": "insufficient_scope", "detail": "Dafür ist der Scope customers.write erforderlich. Passen Sie die Scopes des Schlüssels in Klantly an.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Nicht gefunden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Nicht gefunden.", "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": "Diese Aktion ist im aktuellen Status nicht möglich.", "value": { "type": "https://developers.klantly.com/errors/invalid_state_transition", "title": "Diese Aktion ist im aktuellen Status nicht möglich.", "status": 409, "code": "invalid_state_transition", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_in_progress": { "summary": "Eine Anfrage mit diesem Idempotency-Key wird noch verarbeitet.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Eine Anfrage mit diesem Idempotency-Key wird noch verarbeitet.", "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": "Dieser Idempotency-Key wurde bereits für eine andere Anfrage verwendet.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Dieser Idempotency-Key wurde bereits für eine andere Anfrage verwendet.", "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": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals/{deal}/lose": { "post": { "operationId": "dealsLose", "summary": "Deal verlieren", "description": "Verschiebt den Deal in die Phase, die Ihr Unternehmen als verloren eingerichtet hat, optional mit einem Grund.", "tags": [ "Deals" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/de/reference/deals#dealslose" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "Die ID (UUID) des Deals.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Ein eindeutiger Schlüssel pro Anfrage (zum Beispiel eine UUID): Ein erneuter Versuch erzeugt dann keinen doppelten Datensatz. 24 Stunden gültig.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealsLoseRequest" }, "example": { "lost_reason": "Te duur" } } } }, "responses": { "200": { "description": "Erfolgreich", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "schema": { "type": "string" } }, "ETag": { "description": "Version des Objekts, für 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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "status": 403, "code": "insufficient_scope", "detail": "Dafür ist der Scope customers.write erforderlich. Passen Sie die Scopes des Schlüssels in Klantly an.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Nicht gefunden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Nicht gefunden.", "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": "Diese Aktion ist im aktuellen Status nicht möglich.", "value": { "type": "https://developers.klantly.com/errors/invalid_state_transition", "title": "Diese Aktion ist im aktuellen Status nicht möglich.", "status": 409, "code": "invalid_state_transition", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_in_progress": { "summary": "Eine Anfrage mit diesem Idempotency-Key wird noch verarbeitet.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Eine Anfrage mit diesem Idempotency-Key wird noch verarbeitet.", "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": "Der Body der Anfrage ist zu groß.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "Der Body der Anfrage ist zu groß.", "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": "Dieses Format wird nicht unterstützt.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Dieses Format wird nicht unterstützt.", "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": "Die Eingabe ist ungültig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Die Eingabe ist ungültig.", "status": 422, "code": "validation_failed", "detail": "1 Feld ist ungültig.", "errors": { "email": [ "Email muss eine gültige E-Mail-Adresse sein." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "Die Eingabe enthält ein unbekanntes Feld.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "Die Eingabe enthält ein unbekanntes Feld.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_key_reused": { "summary": "Dieser Idempotency-Key wurde bereits für eine andere Anfrage verwendet.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Dieser Idempotency-Key wurde bereits für eine andere Anfrage verwendet.", "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": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals/{deal}/archive": { "post": { "operationId": "dealsArchive", "summary": "Deal archivieren", "description": "Nimmt den Deal vom Board, ohne ihn zu löschen. Deals lassen sich über die API nicht löschen.", "tags": [ "Deals" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/de/reference/deals#dealsarchive" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "Die ID (UUID) des Deals.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Ein eindeutiger Schlüssel pro Anfrage (zum Beispiel eine UUID): Ein erneuter Versuch erzeugt dann keinen doppelten Datensatz. 24 Stunden gültig.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Erfolgreich", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "schema": { "type": "string" } }, "ETag": { "description": "Version des Objekts, für 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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "status": 403, "code": "insufficient_scope", "detail": "Dafür ist der Scope customers.write erforderlich. Passen Sie die Scopes des Schlüssels in Klantly an.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Nicht gefunden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Nicht gefunden.", "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": "Eine Anfrage mit diesem Idempotency-Key wird noch verarbeitet.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Eine Anfrage mit diesem Idempotency-Key wird noch verarbeitet.", "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": "Dieser Idempotency-Key wurde bereits für eine andere Anfrage verwendet.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Dieser Idempotency-Key wurde bereits für eine andere Anfrage verwendet.", "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": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/deals/{deal}/unarchive": { "post": { "operationId": "dealsUnarchive", "summary": "Deal wiederherstellen", "description": "Setzt einen archivierten Deal zurück auf das Board.", "tags": [ "Deals" ], "x-klantly-scope": "deals.write", "externalDocs": { "url": "https://developers.klantly.com/de/reference/deals#dealsunarchive" }, "parameters": [ { "name": "deal", "in": "path", "required": true, "description": "Die ID (UUID) des Deals.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Ein eindeutiger Schlüssel pro Anfrage (zum Beispiel eine UUID): Ein erneuter Versuch erzeugt dann keinen doppelten Datensatz. 24 Stunden gültig.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Erfolgreich", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "schema": { "type": "string" } }, "ETag": { "description": "Version des Objekts, für 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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "status": 403, "code": "insufficient_scope", "detail": "Dafür ist der Scope customers.write erforderlich. Passen Sie die Scopes des Schlüssels in Klantly an.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Nicht gefunden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Nicht gefunden.", "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": "Eine Anfrage mit diesem Idempotency-Key wird noch verarbeitet.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Eine Anfrage mit diesem Idempotency-Key wird noch verarbeitet.", "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": "Dieser Idempotency-Key wurde bereits für eine andere Anfrage verwendet.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Dieser Idempotency-Key wurde bereits für eine andere Anfrage verwendet.", "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": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/webhook-endpoints": { "get": { "operationId": "webhookEndpointsList", "summary": "Webhook-Endpunkte auflisten", "description": "Alle Webhook-Endpunkte Ihres Unternehmens, älteste zuerst. Das Secret ist nie enthalten.", "tags": [ "Webhook-Endpunkte" ], "x-klantly-scope": "webhooks.manage", "externalDocs": { "url": "https://developers.klantly.com/de/reference/webhook-endpoints#webhook-endpointslist" }, "responses": { "200": { "description": "Erfolgreich", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "status": 403, "code": "insufficient_scope", "detail": "Dafür ist der Scope customers.write erforderlich. Passen Sie die Scopes des Schlüssels in Klantly an.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "post": { "operationId": "webhookEndpointsCreate", "summary": "Webhook-Endpunkt erstellen", "description": "Registriert eine https-Adresse, die Events empfängt. Die Antwort enthält das Secret zum Prüfen der Signatur: Speichern Sie es sofort, Sie sehen es danach nicht mehr. Sie können nur Events zu Daten wählen, auf die Ihr Schlüssel Leserechte hat; * bedeutet alle Events darunter, auch künftige. Höchstens 10 Endpunkte pro Unternehmen.", "tags": [ "Webhook-Endpunkte" ], "x-klantly-scope": "webhooks.manage", "externalDocs": { "url": "https://developers.klantly.com/de/reference/webhook-endpoints#webhook-endpointscreate" }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Ein eindeutiger Schlüssel pro Anfrage (zum Beispiel eine UUID): Ein erneuter Versuch erzeugt dann keinen doppelten Datensatz. 24 Stunden gültig.", "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": "Erstellt", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "schema": { "type": "string" } }, "ETag": { "description": "Version des Objekts, für 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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "status": 403, "code": "insufficient_scope", "detail": "Dafür ist der Scope customers.write erforderlich. Passen Sie die Scopes des Schlüssels in Klantly an.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "limit_reached": { "summary": "Das Limit des Abonnements ist erreicht.", "value": { "type": "https://developers.klantly.com/errors/limit_reached", "title": "Das Limit des Abonnements ist erreicht.", "status": 403, "code": "limit_reached", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Eine Anfrage mit diesem Idempotency-Key wird noch verarbeitet.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Eine Anfrage mit diesem Idempotency-Key wird noch verarbeitet.", "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": "Der Body der Anfrage ist zu groß.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "Der Body der Anfrage ist zu groß.", "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": "Dieses Format wird nicht unterstützt.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Dieses Format wird nicht unterstützt.", "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": "Die Eingabe ist ungültig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Die Eingabe ist ungültig.", "status": 422, "code": "validation_failed", "detail": "1 Feld ist ungültig.", "errors": { "email": [ "Email muss eine gültige E-Mail-Adresse sein." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "Die Eingabe enthält ein unbekanntes Feld.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "Die Eingabe enthält ein unbekanntes Feld.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_key_reused": { "summary": "Dieser Idempotency-Key wurde bereits für eine andere Anfrage verwendet.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Dieser Idempotency-Key wurde bereits für eine andere Anfrage verwendet.", "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": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/webhook-endpoints/{endpoint}": { "get": { "operationId": "webhookEndpointsGet", "summary": "Webhook-Endpunkt abrufen", "description": "Ein Endpunkt nach ID, mit Status und dem Zeitpunkt der letzten erfolgreichen und fehlgeschlagenen Zustellung.", "tags": [ "Webhook-Endpunkte" ], "x-klantly-scope": "webhooks.manage", "externalDocs": { "url": "https://developers.klantly.com/de/reference/webhook-endpoints#webhook-endpointsget" }, "parameters": [ { "name": "endpoint", "in": "path", "required": true, "description": "Die ID des Webhook-Endpunkts.", "schema": { "type": "string", "pattern": "^[0-9a-z]{26}$" } } ], "responses": { "200": { "description": "Erfolgreich", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "schema": { "type": "string" } }, "ETag": { "description": "Version des Objekts, für 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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "status": 403, "code": "insufficient_scope", "detail": "Dafür ist der Scope customers.write erforderlich. Passen Sie die Scopes des Schlüssels in Klantly an.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Nicht gefunden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Nicht gefunden.", "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": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "patch": { "operationId": "webhookEndpointsUpdate", "summary": "Webhook-Endpunkt bearbeiten", "description": "Ändert nur die Felder, die Sie mitsenden. Mit status schalten Sie den Endpunkt aus oder wieder ein; das Wiedereinschalten setzt den Fehlerzähler zurück.", "tags": [ "Webhook-Endpunkte" ], "x-klantly-scope": "webhooks.manage", "externalDocs": { "url": "https://developers.klantly.com/de/reference/webhook-endpoints#webhook-endpointsupdate" }, "parameters": [ { "name": "endpoint", "in": "path", "required": true, "description": "Die ID des Webhook-Endpunkts.", "schema": { "type": "string", "pattern": "^[0-9a-z]{26}$" } }, { "name": "If-Match", "in": "header", "required": false, "description": "Das ETag der abgerufenen Version. Wurde der Datensatz inzwischen geändert, folgt 412.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointsUpdateRequest" }, "example": { "events": [ "*" ], "status": "active" } } } }, "responses": { "200": { "description": "Erfolgreich", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "schema": { "type": "string" } }, "ETag": { "description": "Version des Objekts, für 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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "status": 403, "code": "insufficient_scope", "detail": "Dafür ist der Scope customers.write erforderlich. Passen Sie die Scopes des Schlüssels in Klantly an.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Nicht gefunden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Nicht gefunden.", "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": "Der Datensatz wurde inzwischen geändert.", "value": { "type": "https://developers.klantly.com/errors/precondition_failed", "title": "Der Datensatz wurde inzwischen geändert.", "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": "Der Body der Anfrage ist zu groß.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "Der Body der Anfrage ist zu groß.", "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": "Dieses Format wird nicht unterstützt.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Dieses Format wird nicht unterstützt.", "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": "Die Eingabe ist ungültig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Die Eingabe ist ungültig.", "status": 422, "code": "validation_failed", "detail": "1 Feld ist ungültig.", "errors": { "email": [ "Email muss eine gültige E-Mail-Adresse sein." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "Die Eingabe enthält ein unbekanntes Feld.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "Die Eingabe enthält ein unbekanntes Feld.", "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": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } }, "delete": { "operationId": "webhookEndpointsDelete", "summary": "Webhook-Endpunkt löschen", "description": "Löscht den Endpunkt. Events, die noch unterwegs sind, werden nicht mehr zugestellt.", "tags": [ "Webhook-Endpunkte" ], "x-klantly-scope": "webhooks.manage", "externalDocs": { "url": "https://developers.klantly.com/de/reference/webhook-endpoints#webhook-endpointsdelete" }, "parameters": [ { "name": "endpoint", "in": "path", "required": true, "description": "Die ID des Webhook-Endpunkts.", "schema": { "type": "string", "pattern": "^[0-9a-z]{26}$" } } ], "responses": { "200": { "description": "Erfolgreich", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "schema": { "type": "string" } }, "ETag": { "description": "Version des Objekts, für 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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "status": 403, "code": "insufficient_scope", "detail": "Dafür ist der Scope customers.write erforderlich. Passen Sie die Scopes des Schlüssels in Klantly an.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Nicht gefunden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Nicht gefunden.", "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": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/webhook-endpoints/{endpoint}/test": { "post": { "operationId": "webhookEndpointsTest", "summary": "Testnachricht senden", "description": "Sendet das Event ping sofort an den Endpunkt, auch wenn er deaktiviert ist, und gibt den Zustellversuch zurück. Eine Testnachricht wird nicht wiederholt.", "tags": [ "Webhook-Endpunkte" ], "x-klantly-scope": "webhooks.manage", "externalDocs": { "url": "https://developers.klantly.com/de/reference/webhook-endpoints#webhook-endpointstest" }, "parameters": [ { "name": "endpoint", "in": "path", "required": true, "description": "Die ID des Webhook-Endpunkts.", "schema": { "type": "string", "pattern": "^[0-9a-z]{26}$" } } ], "responses": { "200": { "description": "Erfolgreich", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "schema": { "type": "string" } }, "ETag": { "description": "Version des Objekts, für 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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "status": 403, "code": "insufficient_scope", "detail": "Dafür ist der Scope customers.write erforderlich. Passen Sie die Scopes des Schlüssels in Klantly an.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Nicht gefunden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Nicht gefunden.", "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": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/webhook-endpoints/{endpoint}/rotate-secret": { "post": { "operationId": "webhookEndpointsRotateSecret", "summary": "Secret erneuern", "description": "Erstellt ein neues Secret und gibt es einmalig zurück. Während der Überlappung signiert Klantly mit dem alten und dem neuen Secret, sodass Ihr Empfänger ohne Unterbrechung umstellen kann.", "tags": [ "Webhook-Endpunkte" ], "x-klantly-scope": "webhooks.manage", "externalDocs": { "url": "https://developers.klantly.com/de/reference/webhook-endpoints#webhook-endpointsrotate-secret" }, "parameters": [ { "name": "endpoint", "in": "path", "required": true, "description": "Die ID des Webhook-Endpunkts.", "schema": { "type": "string", "pattern": "^[0-9a-z]{26}$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Ein eindeutiger Schlüssel pro Anfrage (zum Beispiel eine UUID): Ein erneuter Versuch erzeugt dann keinen doppelten Datensatz. 24 Stunden gültig.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointsRotateSecretRequest" }, "example": { "overlap_hours": 24 } } } }, "responses": { "200": { "description": "Erfolgreich", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "schema": { "type": "string" } }, "ETag": { "description": "Version des Objekts, für 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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "status": 403, "code": "insufficient_scope", "detail": "Dafür ist der Scope customers.write erforderlich. Passen Sie die Scopes des Schlüssels in Klantly an.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Nicht gefunden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Nicht gefunden.", "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": "Eine Anfrage mit diesem Idempotency-Key wird noch verarbeitet.", "value": { "type": "https://developers.klantly.com/errors/idempotency_in_progress", "title": "Eine Anfrage mit diesem Idempotency-Key wird noch verarbeitet.", "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": "Der Body der Anfrage ist zu groß.", "value": { "type": "https://developers.klantly.com/errors/payload_too_large", "title": "Der Body der Anfrage ist zu groß.", "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": "Dieses Format wird nicht unterstützt.", "value": { "type": "https://developers.klantly.com/errors/unsupported_media_type", "title": "Dieses Format wird nicht unterstützt.", "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": "Die Eingabe ist ungültig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Die Eingabe ist ungültig.", "status": 422, "code": "validation_failed", "detail": "1 Feld ist ungültig.", "errors": { "email": [ "Email muss eine gültige E-Mail-Adresse sein." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "unknown_field": { "summary": "Die Eingabe enthält ein unbekanntes Feld.", "value": { "type": "https://developers.klantly.com/errors/unknown_field", "title": "Die Eingabe enthält ein unbekanntes Feld.", "status": 422, "code": "unknown_field", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "idempotency_key_reused": { "summary": "Dieser Idempotency-Key wurde bereits für eine andere Anfrage verwendet.", "value": { "type": "https://developers.klantly.com/errors/idempotency_key_reused", "title": "Dieser Idempotency-Key wurde bereits für eine andere Anfrage verwendet.", "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": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/events": { "get": { "operationId": "eventsList", "summary": "Events auflisten", "description": "Die Events der letzten 30 Tage, neueste zuerst. Sie sehen nur Events zu Daten, auf die Ihr Schlüssel Leserechte hat. Mit sort=created_at und filter[created_since] holen Sie verpasste Events der Reihe nach nach.", "tags": [ "Events" ], "x-klantly-scope": "events.read", "externalDocs": { "url": "https://developers.klantly.com/de/reference/events#eventslist" }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Anzahl der Ergebnisse pro Seite.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Der next_cursor oder prev_cursor aus meta der vorherigen Antwort.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "created_at hält die Reihenfolge ein, in der alles geschah, -created_at (Standard) zeigt das Neueste zuerst.", "schema": { "type": "string", "enum": [ "-created_at", "created_at" ], "default": "-created_at" } }, { "name": "filter[type]", "in": "query", "required": false, "description": "Nur diese Event-Typen, durch Kommas getrennt, zum Beispiel customer.created,deal.won.", "schema": { "type": "string", "maxLength": 500 } }, { "name": "filter[created_since]", "in": "query", "required": false, "description": "Nur Events ab diesem Zeitpunkt: ISO 8601 mit Zeitzone, zum Beispiel 2026-09-14T10:15:00Z.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Erfolgreich", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "status": 403, "code": "insufficient_scope", "detail": "Dafür ist der Scope customers.write erforderlich. Passen Sie die Scopes des Schlüssels in Klantly an.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Die Eingabe ist ungültig.", "value": { "type": "https://developers.klantly.com/errors/validation_failed", "title": "Die Eingabe ist ungültig.", "status": 422, "code": "validation_failed", "detail": "1 Feld ist ungültig.", "errors": { "email": [ "Email muss eine gültige E-Mail-Adresse sein." ] }, "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } }, "429": { "description": "rate_limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } }, "/events/{event}": { "get": { "operationId": "eventsGet", "summary": "Event abrufen", "description": "Ein Event nach ID, zum Beispiel die webhook-id einer empfangenen Nachricht.", "tags": [ "Events" ], "x-klantly-scope": "events.read", "externalDocs": { "url": "https://developers.klantly.com/de/reference/events#eventsget" }, "parameters": [ { "name": "event", "in": "path", "required": true, "description": "Die ID des Events (evt_…).", "schema": { "type": "string", "pattern": "^evt_[0-9a-z]{26}$" } } ], "responses": { "200": { "description": "Erfolgreich", "headers": { "X-Request-Id": { "description": "Eindeutige ID dieser Anfrage. Nennen Sie sie bei Fragen an den Support.", "schema": { "type": "string" } }, "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis zum Zurücksetzen des knappsten Limits.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Alle Limits, die für diese Anfrage gelten.", "schema": { "type": "string" } }, "ETag": { "description": "Version des Objekts, für 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": "Authentifizierung erforderlich.", "value": { "type": "https://developers.klantly.com/errors/unauthenticated", "title": "Authentifizierung erforderlich.", "status": 401, "code": "unauthenticated", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "invalid_api_key": { "summary": "Ungültiger API-Schlüssel.", "value": { "type": "https://developers.klantly.com/errors/invalid_api_key", "title": "Ungültiger API-Schlüssel.", "status": 401, "code": "invalid_api_key", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_revoked": { "summary": "Dieser API-Schlüssel wurde widerrufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_revoked", "title": "Dieser API-Schlüssel wurde widerrufen.", "status": 401, "code": "api_key_revoked", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "api_key_expired": { "summary": "Dieser API-Schlüssel ist abgelaufen.", "value": { "type": "https://developers.klantly.com/errors/api_key_expired", "title": "Dieser API-Schlüssel ist abgelaufen.", "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": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "value": { "type": "https://developers.klantly.com/errors/insufficient_scope", "title": "Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.", "status": 403, "code": "insufficient_scope", "detail": "Dafür ist der Scope customers.write erforderlich. Passen Sie die Scopes des Schlüssels in Klantly an.", "required_scope": "customers.write", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "ip_not_allowed": { "summary": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "value": { "type": "https://developers.klantly.com/errors/ip_not_allowed", "title": "Diese IP-Adresse darf diesen API-Schlüssel nicht verwenden.", "status": 403, "code": "ip_not_allowed", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "account_suspended": { "summary": "Das Konto dieses Unternehmens ist gesperrt.", "value": { "type": "https://developers.klantly.com/errors/account_suspended", "title": "Das Konto dieses Unternehmens ist gesperrt.", "status": 403, "code": "account_suspended", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "subscription_inactive": { "summary": "Dieses Unternehmen hat kein aktives Abonnement.", "value": { "type": "https://developers.klantly.com/errors/subscription_inactive", "title": "Dieses Unternehmen hat kein aktives Abonnement.", "status": 403, "code": "subscription_inactive", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } }, "feature_not_available": { "summary": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "value": { "type": "https://developers.klantly.com/errors/feature_not_available", "title": "Diese Funktion ist für dieses Unternehmen nicht verfügbar.", "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": "Nicht gefunden.", "value": { "type": "https://developers.klantly.com/errors/not_found", "title": "Nicht gefunden.", "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": "Zu viele Anfragen.", "value": { "type": "https://developers.klantly.com/errors/rate_limited", "title": "Zu viele Anfragen.", "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": "Bei uns ist etwas schiefgelaufen.", "value": { "type": "https://developers.klantly.com/errors/server_error", "title": "Bei uns ist etwas schiefgelaufen.", "status": 500, "code": "server_error", "request_id": "req_01j7zq3k9x2m4n6p8r0t2v4w6y" } } } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API-Schlüssel Ihres Unternehmens (kly_…), zu erstellen in Klantly unter Integrationen → API." } }, "schemas": { "Problem": { "type": "object", "description": "Ein Fehler nach RFC 9457 (Problem Details).", "required": [ "type", "title", "status", "code" ], "properties": { "type": { "type": "string", "format": "uri", "description": "URL der Seite, die diesen Fehler erklärt." }, "title": { "type": "string", "description": "Kurze Beschreibung, in der Sprache der Anfrage." }, "status": { "type": "integer", "description": "HTTP-Statuscode." }, "code": { "type": "string", "enum": [ "bad_request", "unauthenticated", "invalid_api_key", "api_key_revoked", "api_key_expired", "ip_not_allowed", "account_suspended", "subscription_inactive", "feature_not_available", "insufficient_scope", "forbidden", "limit_reached", "not_found", "method_not_allowed", "conflict", "invalid_state_transition", "idempotency_in_progress", "precondition_failed", "payload_too_large", "unsupported_media_type", "validation_failed", "unknown_field", "idempotency_key_reused", "rate_limited", "server_error", "api_disabled" ], "description": "Fester, englischer Fehlercode: Programmieren Sie darauf." }, "detail": { "type": "string", "description": "Erklärung zu diesem konkreten Fehler." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Validierungsfehler pro Feld." }, "request_id": { "type": "string", "description": "ID der Anfrage, für den Support." } } }, "ListMeta": { "type": "object", "required": [ "limit", "next_cursor", "prev_cursor" ], "properties": { "limit": { "type": "integer", "description": "Anzahl der Ergebnisse pro Seite.", "examples": [ 50 ] }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor für die nächste Seite, oder null auf der letzten Seite.", "examples": [ "eyJpZCI6IjlkM2Y2YzFlIn0" ] }, "prev_cursor": { "type": [ "string", "null" ], "description": "Cursor für die vorherige Seite, oder null auf der ersten Seite.", "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": "Immer „customer“.", "examples": [ "customer" ] }, "id": { "type": "string", "format": "uuid", "description": "Eindeutige ID (UUID).", "examples": [ "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" ] }, "type": { "type": "string", "enum": [ "individual", "business" ], "description": "individual (Privatperson) oder business (Unternehmen).", "examples": [ "business" ] }, "status": { "type": "string", "enum": [ "lead", "customer" ], "description": "lead oder customer (Kunde).", "examples": [ "lead" ] }, "name": { "type": [ "string", "null" ], "description": "Name der Kontaktperson.", "examples": [ "Jan de Vries" ] }, "email": { "type": "string", "format": "email", "description": "E-Mail-Adresse; eindeutig innerhalb Ihres Unternehmens.", "examples": [ "jan@example.com" ] }, "phone": { "type": [ "string", "null" ], "description": "Telefonnummer.", "examples": [ "+31 6 12345678" ] }, "company_name": { "type": [ "string", "null" ], "description": "Firmenname, bei einem Geschäftskunden.", "examples": [ "De Vries Bouw" ] }, "vat_number": { "type": [ "string", "null" ], "description": "USt-IdNr.", "examples": [ "NL123456789B01" ] }, "coc_number": { "type": [ "string", "null" ], "description": "Handelsregisternummer.", "examples": [ "12345678" ] }, "address": { "type": [ "string", "null" ], "description": "Straße und Hausnummer.", "examples": [ "Dorpsstraat 1" ] }, "postal_code": { "type": [ "string", "null" ], "description": "Postleitzahl.", "examples": [ "3511 AB" ] }, "city": { "type": [ "string", "null" ], "description": "Ort.", "examples": [ "Utrecht" ] }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Land.", "examples": [ "NL" ] }, "email_unsubscribed": { "type": "boolean", "description": "Hat sich von E-Mails abgemeldet.", "examples": [ false ] }, "converted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Wann der Lead zum Kunden wurde.", "examples": [ null ] }, "last_activity_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Letzte Aktivität in Klantly.", "examples": [ "2026-09-14T10:15:00Z" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Erstellt am (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Zuletzt geändert am (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": "Immer „api_key“.", "examples": [ "api_key" ] }, "id": { "type": "string", "description": "ID des Schlüssels.", "examples": [ "01j7zq3k9x2m4n6p8r0t2v4w6y" ] }, "name": { "type": "string", "description": "Der Name, den der Schlüssel in Klantly erhalten hat.", "examples": [ "Website" ] }, "prefix": { "type": "string", "description": "Der Anfang des Schlüssels, um ihn zu erkennen.", "examples": [ "kly_4fZ2mQ8v" ] }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Die Scopes des Schlüssels.", "examples": [ [ "customers.read", "customers.write" ] ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Ablaufdatum, oder null, wenn der Schlüssel nicht abläuft.", "examples": [ "2027-09-14T10:15:00Z" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Erstellt am (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "company": { "description": "Das Unternehmen, zu dem der Schlüssel gehört.", "type": "object", "required": [ "object", "id", "name" ], "properties": { "object": { "type": "string", "const": "company", "description": "Immer „company“.", "examples": [ "company" ] }, "id": { "type": "string", "description": "ID des Unternehmens.", "examples": [ "42" ] }, "name": { "type": "string", "description": "Name des Unternehmens.", "examples": [ "De Vries Bouw" ] } }, "additionalProperties": false }, "rate_limits": { "type": "array", "items": { "type": "object", "required": [ "name", "limit", "window_seconds" ], "properties": { "name": { "type": "string", "description": "Name des Limits.", "examples": [ "key_minute" ] }, "limit": { "type": "integer", "description": "Höchstzahl der Anfragen im Zeitfenster.", "examples": [ 120 ] }, "window_seconds": { "type": "integer", "description": "Länge des Zeitfensters in Sekunden.", "examples": [ 60 ] } }, "additionalProperties": false }, "description": "Die Limits, die für diesen Schlüssel gelten.", "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": "Immer „company“.", "examples": [ "company" ] }, "id": { "type": "string", "description": "ID des Unternehmens.", "examples": [ "42" ] }, "name": { "type": "string", "description": "Name des Unternehmens.", "examples": [ "De Vries Bouw" ] }, "email": { "type": [ "string", "null" ], "description": "Allgemeine E-Mail-Adresse.", "examples": [ "info@devriesbouw.nl" ] }, "phone": { "type": [ "string", "null" ], "description": "Telefonnummer.", "examples": [ "+31 30 1234567" ] }, "website": { "type": [ "string", "null" ], "description": "Website.", "examples": [ "https://devriesbouw.nl" ] }, "coc_number": { "type": [ "string", "null" ], "description": "Handelsregisternummer.", "examples": [ "12345678" ] }, "vat_number": { "type": [ "string", "null" ], "description": "USt-IdNr.", "examples": [ "NL123456789B01" ] }, "address": { "type": [ "string", "null" ], "description": "Straße und Hausnummer.", "examples": [ "Industrieweg 5" ] }, "postal_code": { "type": [ "string", "null" ], "description": "Postleitzahl.", "examples": [ "3542 AD" ] }, "city": { "type": [ "string", "null" ], "description": "Ort.", "examples": [ "Utrecht" ] }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Land als zweistelliger ISO-Code (zum Beispiel DE).", "examples": [ "NL" ] }, "language": { "type": "string", "enum": [ "nl", "en", "de", "fr" ], "description": "Hauptsprache des Unternehmens.", "examples": [ "nl" ] }, "currency": { "type": "string", "const": "EUR", "description": "Immer „EUR“.", "examples": [ "EUR" ] }, "timezone": { "type": "string", "description": "Zeitzone, in der Klantly dem Unternehmen Zeiten anzeigt. Die API gibt Zeiten immer in UTC zurück.", "examples": [ "Europe/Amsterdam" ] }, "default_vat_rate": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "description": "Standard-Steuersatz in Prozent, als Text mit zwei Dezimalstellen.", "examples": [ "21.00" ] }, "prices_include_vat": { "type": "boolean", "description": "Ob Preise standardmäßig inklusive Umsatzsteuer eingegeben werden.", "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": "Immer „user“.", "examples": [ "user" ] }, "id": { "type": "string", "description": "ID des Benutzers.", "examples": [ "7" ] }, "name": { "type": "string", "description": "Name.", "examples": [ "Sanne Bakker" ] }, "email": { "type": "string", "format": "email", "description": "E-Mail-Adresse.", "examples": [ "sanne@devriesbouw.nl" ] }, "role": { "type": [ "string", "null" ], "description": "Name der Rolle in Ihrem Unternehmen, oder null ohne Rolle.", "examples": [ "Verkoop" ] }, "is_owner": { "type": "boolean", "description": "Der Inhaber des Kontos.", "examples": [ false ] }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "active oder inactive (deaktiviert).", "examples": [ "active" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Erstellt am (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": "Immer „customer_activity“.", "examples": [ "customer_activity" ] }, "id": { "type": "string", "format": "uuid", "description": "Eindeutige ID (UUID).", "examples": [ "9d3f7c62-3e7a-4f9d-8c4b-5a6e7f8a9ba3" ] }, "customer_id": { "type": "string", "format": "uuid", "description": "Der Kunde, zu dem die Aktivität gehört.", "examples": [ "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" ] }, "type": { "type": "string", "description": "Art der Aktivität, zum Beispiel quote_sent, invoice_created oder appointment_created. Es können Arten hinzukommen: Gehen Sie mit einem unbekannten Wert sauber um.", "examples": [ "quote_sent" ] }, "title": { "type": [ "string", "null" ], "description": "Kurze Beschreibung.", "examples": [ null ] }, "description": { "type": [ "string", "null" ], "description": "Erläuterung.", "examples": [ null ] }, "related": { "description": "Verweise auf verknüpfte Datensätze; nur die zutreffenden haben einen Wert.", "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 des verknüpften Angebots.", "examples": [ null ] }, "invoice_id": { "type": [ "string", "null" ], "description": "ID der verknüpften Rechnung.", "examples": [ null ] }, "appointment_id": { "type": [ "string", "null" ], "description": "ID des verknüpften Termins.", "examples": [ null ] }, "work_order_id": { "type": [ "string", "null" ], "description": "ID des verknüpften Arbeitsauftrags.", "examples": [ null ] }, "task_id": { "type": [ "string", "null" ], "description": "ID der verknüpften Aufgabe.", "examples": [ null ] }, "deal_id": { "type": [ "string", "null" ], "description": "ID des verknüpften Deals.", "examples": [ null ] }, "order_id": { "type": [ "string", "null" ], "description": "ID der verknüpften Bestellung.", "examples": [ null ] }, "conversation_id": { "type": [ "string", "null" ], "description": "ID des verknüpften Gesprächs.", "examples": [ null ] } }, "additionalProperties": false }, "happened_at": { "type": "string", "format": "date-time", "description": "Wann es geschah (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Erfasst am (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": "Immer „note“.", "examples": [ "note" ] }, "id": { "type": "string", "format": "uuid", "description": "Eindeutige ID (UUID).", "examples": [ "9d3f7b41-2d6f-4e8c-9b3a-4f5d6e7a8b92" ] }, "content": { "type": "string", "description": "Der Text der Notiz.", "examples": [ "Klant belt terug na de vakantie." ] }, "is_important": { "type": "boolean", "description": "Als wichtig markiert.", "examples": [ true ] }, "parent": { "description": "Wozu die Notiz gehört.", "type": "object", "required": [ "object", "id" ], "properties": { "object": { "type": "string", "enum": [ "customer", "deal" ], "description": "„customer“ oder „deal“.", "examples": [ "customer" ] }, "id": { "type": "string", "format": "uuid", "description": "ID des Kunden oder Deals.", "examples": [ "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" ] } }, "additionalProperties": false }, "author": { "description": "Wer die Notiz geschrieben hat, oder null bei einer Notiz über die API.", "type": [ "object", "null" ], "required": [ "object", "id", "name" ], "properties": { "object": { "type": "string", "const": "user", "description": "Immer „user“.", "examples": [ "user" ] }, "id": { "type": "string", "description": "ID des Benutzers.", "examples": [ "7" ] }, "name": { "type": "string", "description": "Name des Benutzers.", "examples": [ "Sanne Bakker" ] } }, "additionalProperties": false }, "created_at": { "type": "string", "format": "date-time", "description": "Erstellt am (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Zuletzt geändert am (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": "Immer „pipeline_stage“.", "examples": [ "pipeline_stage" ] }, "id": { "type": "string", "description": "ID der Phase.", "examples": [ "3" ] }, "name": { "type": "string", "description": "Name in der Sprache der Anfrage.", "examples": [ "Offerte verstuurd" ] }, "names": { "description": "Der Name in allen vier Sprachen.", "type": "object", "required": [ "nl", "en", "de", "fr" ], "properties": { "nl": { "type": [ "string", "null" ], "description": "Niederländischer Name.", "examples": [ "Offerte verstuurd" ] }, "en": { "type": [ "string", "null" ], "description": "Englischer Name.", "examples": [ "Quote sent" ] }, "de": { "type": [ "string", "null" ], "description": "Deutscher Name.", "examples": [ "Angebot gesendet" ] }, "fr": { "type": [ "string", "null" ], "description": "Französischer Name.", "examples": [ "Devis envoyé" ] } }, "additionalProperties": false }, "type": { "type": "string", "enum": [ "open", "won", "lost" ], "description": "open, won (gewonnen) oder lost (verloren): Ein Deal in dieser Phase erhält diesen Status.", "examples": [ "open" ] }, "is_default": { "type": "boolean", "description": "Neue Deals landen in dieser Phase.", "examples": [ false ] }, "position": { "type": "integer", "description": "Position auf dem Board, von links nach rechts.", "examples": [ 3 ] }, "probability": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "description": "Gewinnwahrscheinlichkeit in Prozent, als Text mit zwei Dezimalstellen.", "examples": [ "50.00" ] }, "color": { "type": [ "string", "null" ], "description": "Farbe auf dem 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": "Immer „deal“.", "examples": [ "deal" ] }, "id": { "type": "string", "format": "uuid", "description": "Eindeutige ID (UUID).", "examples": [ "9d3f7a20-1c5e-4d7b-8a2f-3e4c5d6f7a81" ] }, "title": { "type": "string", "description": "Titel des Deals.", "examples": [ "Veranda 5x3 m" ] }, "description": { "type": [ "string", "null" ], "description": "Beschreibung.", "examples": [ null ] }, "status": { "type": "string", "enum": [ "open", "won", "lost" ], "description": "open, won (gewonnen) oder lost (verloren); ergibt sich aus der Phase.", "examples": [ "open" ] }, "value": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "description": "Wert als Text mit zwei Dezimalstellen, zum Beispiel „8450.00“. Beim Erstellen und Bearbeiten dürfen Sie auch eine Zahl senden.", "examples": [ "8450.00" ] }, "currency": { "type": "string", "const": "EUR", "description": "Immer „EUR“.", "examples": [ "EUR" ] }, "value_source": { "type": "string", "enum": [ "quotes", "manual" ], "description": "quotes: Der Wert ergibt sich aus den verknüpften Angeboten; manual: von Hand festgelegt.", "examples": [ "manual" ] }, "stage": { "description": "Die Phase, in der der Deal steht; die Namen stehen in Pipeline-Phasen auflisten.", "type": [ "object", "null" ], "required": [ "object", "id" ], "properties": { "object": { "type": "string", "const": "pipeline_stage", "description": "Immer „pipeline_stage“.", "examples": [ "pipeline_stage" ] }, "id": { "type": "string", "description": "ID der Phase.", "examples": [ "3" ] } }, "additionalProperties": false }, "customer_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Der Kunde des Deals.", "examples": [ "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" ] }, "assigned_user_id": { "type": [ "string", "null" ], "description": "Der Benutzer, der den Deal betreut, oder null.", "examples": [ "7" ] }, "source": { "type": [ "string", "null" ], "description": "Woher der Deal stammt; über die API ist das api.", "examples": [ "api" ] }, "lost_reason": { "type": [ "string", "null" ], "description": "Warum der Deal verloren wurde, oder null.", "examples": [ null ] }, "is_archived": { "type": "boolean", "description": "Archiviert: nicht mehr auf dem Board.", "examples": [ false ] }, "stage_changed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Wann der Deal zuletzt die Phase gewechselt hat.", "examples": [ "2026-09-14T10:15:00Z" ] }, "won_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Wann der Deal gewonnen wurde.", "examples": [ null ] }, "lost_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Wann der Deal verloren wurde.", "examples": [ null ] }, "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Wann der Deal archiviert wurde.", "examples": [ null ] }, "created_at": { "type": "string", "format": "date-time", "description": "Erstellt am (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Zuletzt geändert am (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] } }, "additionalProperties": false }, "DealAction": { "type": "object", "required": [ "stage_id", "notes" ], "properties": { "stage_id": { "type": "integer", "description": "Die ID der Phase, in die der Deal verschoben wird (aus Pipeline-Phasen auflisten).", "examples": [ 3 ] }, "notes": { "type": [ "string", "null" ], "description": "Optionale Anmerkung; wird mit dem Phasenwechsel im Verlauf des Deals gespeichert.", "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": "Immer „webhook_endpoint“.", "examples": [ "webhook_endpoint" ] }, "id": { "type": "string", "description": "ID des Endpunkts.", "examples": [ "01j7zr8m2k4n6p8r0t2v4w6y8a" ] }, "url": { "type": "string", "format": "uri", "description": "Die https-Adresse, an die Klantly die Events sendet. Keine internen Adressen und nur Port 443, 80 oder 8443.", "examples": [ "https://example.com/webhooks/klantly" ] }, "description": { "type": [ "string", "null" ], "description": "Eigene Beschreibung, zum Beispiel wofür der Endpunkt dient.", "examples": [ "Boekhouding" ] }, "events": { "type": "array", "items": { "type": "string" }, "description": "Die Event-Typen, die dieser Endpunkt empfängt, oder [\"*\"] für alle Events, auf die der Schlüssel oder Benutzer Leserechte hat.", "examples": [ [ "customer.created", "deal.won" ] ] }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "active oder disabled (deaktiviert).", "examples": [ "active" ] }, "disabled_reason": { "type": [ "string", "null" ], "enum": [ "failing", "manual", null, null ], "description": "Warum der Endpunkt aus ist: failing (5 Tage nur Fehler) oder manual (von Hand), sonst null.", "examples": [ null ] }, "disabled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Wann der Endpunkt deaktiviert wurde.", "examples": [ null ] }, "previous_secret_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Bis wann nach einer Erneuerung auch das vorherige Secret noch verwendet wird, sonst null.", "examples": [ null ] }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Letzte erfolgreiche Zustellung.", "examples": [ "2026-09-14T10:15:02Z" ] }, "last_failure_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Letzte fehlgeschlagene Zustellung.", "examples": [ null ] }, "created_at": { "type": "string", "format": "date-time", "description": "Erstellt am (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Zuletzt geändert am (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": "Immer „webhook_endpoint“.", "examples": [ "webhook_endpoint" ] }, "id": { "type": "string", "description": "ID des Endpunkts.", "examples": [ "01j7zr8m2k4n6p8r0t2v4w6y8a" ] }, "url": { "type": "string", "format": "uri", "description": "Die https-Adresse, an die Klantly die Events sendet. Keine internen Adressen und nur Port 443, 80 oder 8443.", "examples": [ "https://example.com/webhooks/klantly" ] }, "description": { "type": [ "string", "null" ], "description": "Eigene Beschreibung, zum Beispiel wofür der Endpunkt dient.", "examples": [ "Boekhouding" ] }, "events": { "type": "array", "items": { "type": "string" }, "description": "Die Event-Typen, die dieser Endpunkt empfängt, oder [\"*\"] für alle Events, auf die der Schlüssel oder Benutzer Leserechte hat.", "examples": [ [ "customer.created", "deal.won" ] ] }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "active oder disabled (deaktiviert).", "examples": [ "active" ] }, "disabled_reason": { "type": [ "string", "null" ], "enum": [ "failing", "manual", null, null ], "description": "Warum der Endpunkt aus ist: failing (5 Tage nur Fehler) oder manual (von Hand), sonst null.", "examples": [ null ] }, "disabled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Wann der Endpunkt deaktiviert wurde.", "examples": [ null ] }, "previous_secret_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Bis wann nach einer Erneuerung auch das vorherige Secret noch verwendet wird, sonst null.", "examples": [ null ] }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Letzte erfolgreiche Zustellung.", "examples": [ "2026-09-14T10:15:02Z" ] }, "last_failure_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Letzte fehlgeschlagene Zustellung.", "examples": [ null ] }, "created_at": { "type": "string", "format": "date-time", "description": "Erstellt am (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Zuletzt geändert am (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "secret": { "type": "string", "pattern": "^whsec_", "description": "Das Secret (whsec_…) zum Prüfen der Signaturen. Nur in dieser Antwort: Speichern Sie es sofort.", "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": "Immer „webhook_delivery“.", "examples": [ "webhook_delivery" ] }, "id": { "type": "string", "description": "ID des Zustellversuchs.", "examples": [ "1834" ] }, "webhook_endpoint_id": { "type": "string", "description": "Der Endpunkt.", "examples": [ "01j7zr8m2k4n6p8r0t2v4w6y8a" ] }, "event_id": { "type": "string", "description": "Das gesendete Event.", "examples": [ "evt_01j7zs1a2b3c4d5e6f7g8h9j0k" ] }, "event_type": { "type": "string", "description": "Der Event-Typ; ping bei einem Test.", "examples": [ "ping" ] }, "attempt": { "type": "integer", "description": "Nummer des Versuchs (1 ist der erste).", "examples": [ 1 ] }, "status": { "type": "string", "enum": [ "succeeded", "failed" ], "description": "succeeded (2xx-Antwort) oder failed.", "examples": [ "succeeded" ] }, "response_status": { "type": [ "integer", "null" ], "description": "HTTP-Status Ihres Servers, oder null, wenn keine Antwort kam.", "examples": [ 200 ] }, "error": { "type": [ "string", "null" ], "description": "Was schiefging, wenn keine Antwort kam, zum Beispiel connection_failed, sonst null.", "examples": [ null ] }, "duration_ms": { "type": "integer", "description": "Dauer des Versuchs in Millisekunden.", "examples": [ 184 ] }, "created_at": { "type": "string", "format": "date-time", "description": "Zeitpunkt des Versuchs (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": "Immer „event“.", "examples": [ "event" ] }, "id": { "type": "string", "pattern": "^evt_", "description": "Eindeutige ID (evt_…). Gleich dem Header webhook-id: Verwenden Sie sie, um doppelte Nachrichten zu erkennen.", "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": "Die Art des Events, zum Beispiel customer.created.", "examples": [ "customer.created" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Wann es geschah (UTC).", "examples": [ "2026-09-14T10:15:00Z" ] }, "data": { "description": "Der Inhalt des Events.", "type": "object", "required": [ "object" ], "properties": { "object": { "type": "object", "description": "Das Objekt, wie es nach der Änderung war, in derselben Form wie in der REST-API (bei note.deleted: wie es vor dem Löschen war).", "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": "Die Art des gelöschten Objekts, zum Beispiel „note“.", "examples": [ "note" ] }, "id": { "type": "string", "description": "ID des gelöschten Objekts.", "examples": [ "9d3f7b41-2d6f-4e8c-9b3a-4f5d6e7a8b92" ] }, "deleted": { "type": "boolean", "const": true, "description": "Immer true.", "examples": [ true ] } }, "additionalProperties": false }, "CustomersCreateRequest": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 255, "x-unique": true, "description": "E-Mail-Adresse; eindeutig innerhalb Ihres Unternehmens." }, "type": { "type": "string", "enum": [ "individual", "business" ], "description": "individual (Privatperson) oder business (Unternehmen)." }, "name": { "type": [ "string", "null" ], "maxLength": 255, "description": "Name der Kontaktperson." }, "phone": { "type": [ "string", "null" ], "maxLength": 255, "description": "Telefonnummer." }, "address": { "type": [ "string", "null" ], "maxLength": 255, "description": "Straße und Hausnummer." }, "city": { "type": [ "string", "null" ], "maxLength": 255, "description": "Ort." }, "postal_code": { "type": [ "string", "null" ], "maxLength": 64, "description": "Postleitzahl." }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "minLength": 2, "maxLength": 2, "description": "Land." }, "company_name": { "type": [ "string", "null" ], "maxLength": 255, "description": "Firmenname, bei einem Geschäftskunden." }, "vat_number": { "type": [ "string", "null" ], "maxLength": 20, "description": "USt-IdNr." }, "coc_number": { "type": [ "string", "null" ], "maxLength": 30, "description": "Handelsregisternummer." } }, "additionalProperties": false }, "CustomersUpdateRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 255, "x-unique": true, "description": "E-Mail-Adresse; eindeutig innerhalb Ihres Unternehmens." }, "type": { "type": "string", "enum": [ "individual", "business" ], "description": "individual (Privatperson) oder business (Unternehmen)." }, "name": { "type": [ "string", "null" ], "maxLength": 255, "description": "Name der Kontaktperson." }, "phone": { "type": [ "string", "null" ], "maxLength": 255, "description": "Telefonnummer." }, "address": { "type": [ "string", "null" ], "maxLength": 255, "description": "Straße und Hausnummer." }, "city": { "type": [ "string", "null" ], "maxLength": 255, "description": "Ort." }, "postal_code": { "type": [ "string", "null" ], "maxLength": 64, "description": "Postleitzahl." }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "minLength": 2, "maxLength": 2, "description": "Land." }, "company_name": { "type": [ "string", "null" ], "maxLength": 255, "description": "Firmenname, bei einem Geschäftskunden." }, "vat_number": { "type": [ "string", "null" ], "maxLength": 20, "description": "USt-IdNr." }, "coc_number": { "type": [ "string", "null" ], "maxLength": 30, "description": "Handelsregisternummer." } }, "additionalProperties": false }, "NotesCreateCustomerRequest": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "maxLength": 10000, "description": "Der Text der Notiz." }, "is_important": { "type": "boolean", "description": "Als wichtig markiert." } }, "additionalProperties": false }, "NotesUpdateCustomerRequest": { "type": "object", "properties": { "content": { "type": "string", "maxLength": 10000, "description": "Der Text der Notiz." }, "is_important": { "type": "boolean", "description": "Als wichtig markiert." } }, "additionalProperties": false }, "NotesCreateDealRequest": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "maxLength": 10000, "description": "Der Text der Notiz." }, "is_important": { "type": "boolean", "description": "Als wichtig markiert." } }, "additionalProperties": false }, "NotesUpdateDealRequest": { "type": "object", "properties": { "content": { "type": "string", "maxLength": 10000, "description": "Der Text der Notiz." }, "is_important": { "type": "boolean", "description": "Als wichtig markiert." } }, "additionalProperties": false }, "DealsCreateRequest": { "type": "object", "required": [ "customer_id" ], "properties": { "customer_id": { "type": "string", "format": "uuid", "description": "Der Kunde des Deals." }, "title": { "type": [ "string", "null" ], "maxLength": 255, "description": "Titel des Deals." }, "description": { "type": [ "string", "null" ], "maxLength": 10000, "description": "Beschreibung." }, "value": { "type": [ "number", "null" ], "minimum": 0, "maximum": 99999999, "multipleOf": 0.01, "description": "Wert als Text mit zwei Dezimalstellen, zum Beispiel „8450.00“. Beim Erstellen und Bearbeiten dürfen Sie auch eine Zahl senden." }, "stage_id": { "type": [ "integer", "null" ], "description": "Die Phase, in die der Deal kommt. Ohne stage_id: die Standardphase." }, "assigned_user_id": { "type": [ "integer", "null" ], "description": "Der Benutzer, der den Deal betreut, oder null." } }, "additionalProperties": false }, "DealsUpdateRequest": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 255, "description": "Titel des Deals." }, "description": { "type": [ "string", "null" ], "maxLength": 10000, "description": "Beschreibung." }, "value": { "type": "number", "minimum": 0, "maximum": 99999999, "multipleOf": 0.01, "description": "Wert als Text mit zwei Dezimalstellen, zum Beispiel „8450.00“. Beim Erstellen und Bearbeiten dürfen Sie auch eine Zahl senden." }, "assigned_user_id": { "type": [ "integer", "null" ], "description": "Der Benutzer, der den Deal betreut, oder null." } }, "additionalProperties": false }, "DealsMoveRequest": { "type": "object", "required": [ "stage_id" ], "properties": { "stage_id": { "type": "integer", "description": "Die ID der Phase, in die der Deal verschoben wird (aus Pipeline-Phasen auflisten)." }, "notes": { "type": [ "string", "null" ], "maxLength": 500, "description": "Optionale Anmerkung; wird mit dem Phasenwechsel im Verlauf des Deals gespeichert." } }, "additionalProperties": false }, "DealsLoseRequest": { "type": "object", "properties": { "lost_reason": { "type": [ "string", "null" ], "maxLength": 255, "description": "Warum der Deal verloren wurde, oder null." } }, "additionalProperties": false }, "WebhookEndpointsCreateRequest": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Die https-Adresse, an die Klantly die Events sendet. Keine internen Adressen und nur Port 443, 80 oder 8443." }, "description": { "type": [ "string", "null" ], "maxLength": 255, "description": "Eigene Beschreibung, zum Beispiel wofür der Endpunkt dient." }, "events": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Die Event-Typen, die dieser Endpunkt empfängt, oder [\"*\"] für alle Events, auf die der Schlüssel oder Benutzer Leserechte hat." } }, "additionalProperties": false }, "WebhookEndpointsUpdateRequest": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Die https-Adresse, an die Klantly die Events sendet. Keine internen Adressen und nur Port 443, 80 oder 8443." }, "description": { "type": [ "string", "null" ], "maxLength": 255, "description": "Eigene Beschreibung, zum Beispiel wofür der Endpunkt dient." }, "events": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Die Event-Typen, die dieser Endpunkt empfängt, oder [\"*\"] für alle Events, auf die der Schlüssel oder Benutzer Leserechte hat." }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "active oder disabled (deaktiviert)." } }, "additionalProperties": false }, "WebhookEndpointsRotateSecretRequest": { "type": "object", "properties": { "overlap_hours": { "type": "integer", "enum": [ "0", "1", "24", "168" ], "description": "Wie lange das alte Secret neben dem neuen weiter funktioniert: 0, 1, 24 (Standard) oder 168 Stunden." } }, "additionalProperties": false } } } }