Deals

Deals auflisten

GET /api/v1/deals

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.

Scope: deals.read — Deals und Pipeline-Phasen lesen
Erforderliche Funktion: pipeline

Query-Parameter

Name	Typ	Beschreibung
`limit`	integer	Anzahl der Ergebnisse pro Seite. von 1 bis 100 · Standard: 50
`cursor`	string	Der next_cursor oder prev_cursor aus meta der vorherigen Antwort.
`sort`	string	Sortierung nach created_at, updated_at oder stage_changed_at; ein Minuszeichen davor bedeutet absteigend. einer von: -created_at, created_at, -updated_at, updated_at, -stage_changed_at, stage_changed_at · Standard: -created_at
`filter[status]`	string	Nur offene, gewonnene oder verlorene Deals. einer von: open, won, lost
`filter[stage_id]`	integer	Nur Deals in dieser Phase (die ID aus Pipeline-Phasen auflisten).
`filter[customer_id]`	string (uuid)	Nur Deals dieses Kunden.
`filter[assigned_user_id]`	integer	Nur Deals dieses Benutzers.
`filter[archived]`	string	false (Standard) zeigt nur Deals auf dem Board, true nur archivierte, all beide. einer von: false, true, all · Standard: false
`filter[updated_since]`	string (date-time)	Nur was seit diesem Zeitpunkt geändert wurde: ISO 8601 mit Zeitzone, zum Beispiel 2026-09-14T10:15:00Z. Praktisch zum Synchronisieren.

Beispielanfrage

cURL

curl "https://app.klantly.com/api/v1/deals?filter[status]=open" \
  -H "Authorization: Bearer $KLANTLY_API_KEY"

PHP

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('GET', 'deals', [
    'query' => [
        'filter[status]' => 'open',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];

JavaScript

const response = await fetch('https://app.klantly.com/api/v1/deals?filter[status]=open', {
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
  },
});

const { data } = await response.json();

Python

import os

import requests

response = requests.get(
    "https://app.klantly.com/api/v1/deals",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
    params={
        "filter[status]": "open"
    },
)
data = response.json()["data"]

Antwort 200

Die Antwort ist eine Liste mit Cursor-Paginierung: data enthält die Objekte, meta die Paginierung.

Beispielantwort

{
  "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
  }
}

Mögliche Fehler

403 insufficient_scope — Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.
422 validation_failed — Die Eingabe ist ungültig.

Zusätzlich kann jeder Endpunkt die allgemeinen Fehler zurückgeben, etwa einen ungültigen Schlüssel oder ein erreichtes Limit. Alle Fehlercodes ansehen.

Deal abrufen

GET /api/v1/deals/{deal}

Ein Deal nach ID. Die Antwort enthält einen ETag, den Sie beim Bearbeiten in If-Match mitsenden können.

Scope: deals.read — Deals und Pipeline-Phasen lesen
Erforderliche Funktion: pipeline

Pfadparameter

Name	Typ	Beschreibung
`deal` erforderlich	string (uuid)	Die ID (UUID) des Deals.

Beispielanfrage

cURL

curl "https://app.klantly.com/api/v1/deals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" \
  -H "Authorization: Bearer $KLANTLY_API_KEY"

PHP

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('GET', 'deals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70');

$data = json_decode((string) $response->getBody(), true)['data'];

JavaScript

const response = await fetch('https://app.klantly.com/api/v1/deals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70', {
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
  },
});

const { data } = await response.json();

Python

import os

import requests

response = requests.get(
    "https://app.klantly.com/api/v1/deals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
)
data = response.json()["data"]

Antwort 200

Beispielantwort

{
  "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"
  }
}

Mögliche Fehler

403 insufficient_scope — Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.
404 not_found — Nicht gefunden.

Zusätzlich kann jeder Endpunkt die allgemeinen Fehler zurückgeben, etwa einen ungültigen Schlüssel oder ein erreichtes Limit. Alle Fehlercodes ansehen.

Deal erstellen

POST /api/v1/deals

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.

Scope: deals.write — Deals erstellen, bearbeiten, verschieben und archivieren
Erforderliche Funktion: pipeline

Senden Sie einen Idempotency-Key mit, dann erzeugt ein erneuter Versuch nach einem Timeout keinen doppelten Datensatz.

Body (JSON)

Feld	Typ	Beschreibung
`customer_id` erforderlich	string (uuid)	Der Kunde des Deals.
`title` optional	string	Titel des Deals. kann leer sein (null) · höchstens 255 Zeichen
`description` optional	string	Beschreibung. kann leer sein (null) · höchstens 10000 Zeichen
`value` optional	number	Wert als Text mit zwei Dezimalstellen, zum Beispiel „8450.00“. Beim Erstellen und Bearbeiten dürfen Sie auch eine Zahl senden. kann leer sein (null) · von 0 bis 99999999
`stage_id` optional	integer	Die Phase, in die der Deal kommt. Ohne stage_id: die Standardphase. kann leer sein (null)
`assigned_user_id` optional	integer	Der Benutzer, der den Deal betreut, oder null. kann leer sein (null)

Beispielanfrage

cURL

curl -X POST "https://app.klantly.com/api/v1/deals" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f" \
  -d '{
  "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
  "title": "Veranda 5x3 m",
  "value": "8450.00"
}'

PHP

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('POST', 'deals', [
    'headers' => [
        'Idempotency-Key' => '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
    ],
    'json' => [
        'customer_id' => '9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70',
        'title' => 'Veranda 5x3 m',
        'value' => '8450.00',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];

JavaScript

const response = await fetch('https://app.klantly.com/api/v1/deals', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
  },
  body: JSON.stringify({
  "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
  "title": "Veranda 5x3 m",
  "value": "8450.00"
}),
});

const { data } = await response.json();

Python

import os

import requests

response = requests.post(
    "https://app.klantly.com/api/v1/deals",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
        "Idempotency-Key": "6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    },
    json={
        "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
        "title": "Veranda 5x3 m",
        "value": "8450.00"
    },
)
data = response.json()["data"]

Antwort 201

Beispielantwort

{
  "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"
  }
}

Mögliche Fehler

403 insufficient_scope — Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.
422 validation_failed — Die Eingabe ist ungültig.
422 unknown_field — Die Eingabe enthält ein unbekanntes Feld.
415 unsupported_media_type — Dieses Format wird nicht unterstützt.
413 payload_too_large — Der Body der Anfrage ist zu groß.
409 conflict — Dies steht im Widerspruch zum aktuellen Zustand.
422 idempotency_key_reused — Dieser Idempotency-Key wurde bereits für eine andere Anfrage verwendet.
409 idempotency_in_progress — Eine Anfrage mit diesem Idempotency-Key wird noch verarbeitet.

Zusätzlich kann jeder Endpunkt die allgemeinen Fehler zurückgeben, etwa einen ungültigen Schlüssel oder ein erreichtes Limit. Alle Fehlercodes ansehen.

Deal bearbeiten

PATCH /api/v1/deals/{deal}

Ändert nur die Felder, die Sie mitsenden. Die Phase ändern Sie mit Verschieben, Gewinnen oder Verlieren. Ein mitgesendeter value setzt value_source auf manual.

Scope: deals.write — Deals erstellen, bearbeiten, verschieben und archivieren
Erforderliche Funktion: pipeline

Senden Sie das ETag in If-Match mit, dann überschreiben Sie nie versehentlich eine neuere Version.

Pfadparameter

Name	Typ	Beschreibung
`deal` erforderlich	string (uuid)	Die ID (UUID) des Deals.

Body (JSON)

Feld	Typ	Beschreibung
`title` optional	string	Titel des Deals. höchstens 255 Zeichen
`description` optional	string	Beschreibung. kann leer sein (null) · höchstens 10000 Zeichen
`value` optional	number	Wert als Text mit zwei Dezimalstellen, zum Beispiel „8450.00“. Beim Erstellen und Bearbeiten dürfen Sie auch eine Zahl senden. von 0 bis 99999999
`assigned_user_id` optional	integer	Der Benutzer, der den Deal betreut, oder null. kann leer sein (null)

Beispielanfrage

cURL

curl -X PATCH "https://app.klantly.com/api/v1/deals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "value": "9100.00",
  "assigned_user_id": 7
}'

PHP

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('PATCH', 'deals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70', [
    'json' => [
        'value' => '9100.00',
        'assigned_user_id' => 7,
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];

JavaScript

const response = await fetch('https://app.klantly.com/api/v1/deals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "value": "9100.00",
  "assigned_user_id": 7
}),
});

const { data } = await response.json();

Python

import os

import requests

response = requests.patch(
    "https://app.klantly.com/api/v1/deals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
    json={
        "value": "9100.00",
        "assigned_user_id": 7
    },
)
data = response.json()["data"]

Antwort 200

Beispielantwort

{
  "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"
  }
}

Mögliche Fehler

403 insufficient_scope — Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.
422 validation_failed — Die Eingabe ist ungültig.
422 unknown_field — Die Eingabe enthält ein unbekanntes Feld.
415 unsupported_media_type — Dieses Format wird nicht unterstützt.
413 payload_too_large — Der Body der Anfrage ist zu groß.
404 not_found — Nicht gefunden.
412 precondition_failed — Der Datensatz wurde inzwischen geändert.

Zusätzlich kann jeder Endpunkt die allgemeinen Fehler zurückgeben, etwa einen ungültigen Schlüssel oder ein erreichtes Limit. Alle Fehlercodes ansehen.

Deal verschieben

POST /api/v1/deals/{deal}/move

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.

Scope: deals.write — Deals erstellen, bearbeiten, verschieben und archivieren
Erforderliche Funktion: pipeline

Senden Sie einen Idempotency-Key mit, dann erzeugt ein erneuter Versuch nach einem Timeout keinen doppelten Datensatz.

Pfadparameter

Name	Typ	Beschreibung
`deal` erforderlich	string (uuid)	Die ID (UUID) des Deals.

Body (JSON)

Feld	Typ	Beschreibung
`stage_id` erforderlich	integer	Die ID der Phase, in die der Deal verschoben wird (aus Pipeline-Phasen auflisten).
`notes` optional	string	Optionale Anmerkung; wird mit dem Phasenwechsel im Verlauf des Deals gespeichert. kann leer sein (null) · höchstens 500 Zeichen

Beispielanfrage

cURL

curl -X POST "https://app.klantly.com/api/v1/deals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/move" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f" \
  -d '{
  "stage_id": 3
}'

PHP

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('POST', 'deals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/move', [
    'headers' => [
        'Idempotency-Key' => '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
    ],
    'json' => [
        'stage_id' => 3,
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];

JavaScript

const response = await fetch('https://app.klantly.com/api/v1/deals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/move', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
  },
  body: JSON.stringify({
  "stage_id": 3
}),
});

const { data } = await response.json();

Python

import os

import requests

response = requests.post(
    "https://app.klantly.com/api/v1/deals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/move",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
        "Idempotency-Key": "6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    },
    json={
        "stage_id": 3
    },
)
data = response.json()["data"]

Antwort 200

Beispielantwort

{
  "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"
  }
}

Mögliche Fehler

403 insufficient_scope — Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.
422 validation_failed — Die Eingabe ist ungültig.
422 unknown_field — Die Eingabe enthält ein unbekanntes Feld.
415 unsupported_media_type — Dieses Format wird nicht unterstützt.
413 payload_too_large — Der Body der Anfrage ist zu groß.
404 not_found — Nicht gefunden.
422 idempotency_key_reused — Dieser Idempotency-Key wurde bereits für eine andere Anfrage verwendet.
409 idempotency_in_progress — Eine Anfrage mit diesem Idempotency-Key wird noch verarbeitet.

Zusätzlich kann jeder Endpunkt die allgemeinen Fehler zurückgeben, etwa einen ungültigen Schlüssel oder ein erreichtes Limit. Alle Fehlercodes ansehen.

Deal gewinnen

POST /api/v1/deals/{deal}/win

Verschiebt den Deal in die Phase, die Ihr Unternehmen als gewonnen eingerichtet hat. Ist er schon gewonnen, ändert sich nichts.

Scope: deals.write — Deals erstellen, bearbeiten, verschieben und archivieren
Erforderliche Funktion: pipeline

Senden Sie einen Idempotency-Key mit, dann erzeugt ein erneuter Versuch nach einem Timeout keinen doppelten Datensatz.

Pfadparameter

Name	Typ	Beschreibung
`deal` erforderlich	string (uuid)	Die ID (UUID) des Deals.

Beispielanfrage

cURL

curl -X POST "https://app.klantly.com/api/v1/deals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/win" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Idempotency-Key: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f"

PHP

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('POST', 'deals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/win', [
    'headers' => [
        'Idempotency-Key' => '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];

JavaScript

const response = await fetch('https://app.klantly.com/api/v1/deals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/win', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Idempotency-Key': '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
  },
});

const { data } = await response.json();

Python

import os

import requests

response = requests.post(
    "https://app.klantly.com/api/v1/deals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/win",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
        "Idempotency-Key": "6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    },
)
data = response.json()["data"]

Antwort 200

Beispielantwort

{
  "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"
  }
}

Mögliche Fehler

403 insufficient_scope — Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.
404 not_found — Nicht gefunden.
409 invalid_state_transition — Diese Aktion ist im aktuellen Status nicht möglich.
422 idempotency_key_reused — Dieser Idempotency-Key wurde bereits für eine andere Anfrage verwendet.
409 idempotency_in_progress — Eine Anfrage mit diesem Idempotency-Key wird noch verarbeitet.

Zusätzlich kann jeder Endpunkt die allgemeinen Fehler zurückgeben, etwa einen ungültigen Schlüssel oder ein erreichtes Limit. Alle Fehlercodes ansehen.

Deal verlieren

POST /api/v1/deals/{deal}/lose

Verschiebt den Deal in die Phase, die Ihr Unternehmen als verloren eingerichtet hat, optional mit einem Grund.

Scope: deals.write — Deals erstellen, bearbeiten, verschieben und archivieren
Erforderliche Funktion: pipeline

Senden Sie einen Idempotency-Key mit, dann erzeugt ein erneuter Versuch nach einem Timeout keinen doppelten Datensatz.

Pfadparameter

Name	Typ	Beschreibung
`deal` erforderlich	string (uuid)	Die ID (UUID) des Deals.

Body (JSON)

Feld	Typ	Beschreibung
`lost_reason` optional	string	Warum der Deal verloren wurde, oder null. kann leer sein (null) · höchstens 255 Zeichen

Beispielanfrage

cURL

curl -X POST "https://app.klantly.com/api/v1/deals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/lose" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f" \
  -d '{
  "lost_reason": "Te duur"
}'

PHP

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('POST', 'deals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/lose', [
    'headers' => [
        'Idempotency-Key' => '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
    ],
    'json' => [
        'lost_reason' => 'Te duur',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];

JavaScript

const response = await fetch('https://app.klantly.com/api/v1/deals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/lose', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
  },
  body: JSON.stringify({
  "lost_reason": "Te duur"
}),
});

const { data } = await response.json();

Python

import os

import requests

response = requests.post(
    "https://app.klantly.com/api/v1/deals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/lose",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
        "Idempotency-Key": "6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    },
    json={
        "lost_reason": "Te duur"
    },
)
data = response.json()["data"]

Antwort 200

Beispielantwort

{
  "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"
  }
}

Mögliche Fehler

403 insufficient_scope — Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.
422 validation_failed — Die Eingabe ist ungültig.
422 unknown_field — Die Eingabe enthält ein unbekanntes Feld.
415 unsupported_media_type — Dieses Format wird nicht unterstützt.
413 payload_too_large — Der Body der Anfrage ist zu groß.
404 not_found — Nicht gefunden.
409 invalid_state_transition — Diese Aktion ist im aktuellen Status nicht möglich.
422 idempotency_key_reused — Dieser Idempotency-Key wurde bereits für eine andere Anfrage verwendet.
409 idempotency_in_progress — Eine Anfrage mit diesem Idempotency-Key wird noch verarbeitet.

Zusätzlich kann jeder Endpunkt die allgemeinen Fehler zurückgeben, etwa einen ungültigen Schlüssel oder ein erreichtes Limit. Alle Fehlercodes ansehen.

Deal archivieren

POST /api/v1/deals/{deal}/archive

Nimmt den Deal vom Board, ohne ihn zu löschen. Deals lassen sich über die API nicht löschen.

Scope: deals.write — Deals erstellen, bearbeiten, verschieben und archivieren
Erforderliche Funktion: pipeline

Senden Sie einen Idempotency-Key mit, dann erzeugt ein erneuter Versuch nach einem Timeout keinen doppelten Datensatz.

Pfadparameter

Name	Typ	Beschreibung
`deal` erforderlich	string (uuid)	Die ID (UUID) des Deals.

Beispielanfrage

cURL

curl -X POST "https://app.klantly.com/api/v1/deals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/archive" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Idempotency-Key: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f"

PHP

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('POST', 'deals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/archive', [
    'headers' => [
        'Idempotency-Key' => '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];

JavaScript

const response = await fetch('https://app.klantly.com/api/v1/deals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/archive', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Idempotency-Key': '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
  },
});

const { data } = await response.json();

Python

import os

import requests

response = requests.post(
    "https://app.klantly.com/api/v1/deals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/archive",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
        "Idempotency-Key": "6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    },
)
data = response.json()["data"]

Antwort 200

Beispielantwort

{
  "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"
  }
}

Mögliche Fehler

403 insufficient_scope — Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.
404 not_found — Nicht gefunden.
422 idempotency_key_reused — Dieser Idempotency-Key wurde bereits für eine andere Anfrage verwendet.
409 idempotency_in_progress — Eine Anfrage mit diesem Idempotency-Key wird noch verarbeitet.

Zusätzlich kann jeder Endpunkt die allgemeinen Fehler zurückgeben, etwa einen ungültigen Schlüssel oder ein erreichtes Limit. Alle Fehlercodes ansehen.

Deal wiederherstellen

POST /api/v1/deals/{deal}/unarchive

Setzt einen archivierten Deal zurück auf das Board.

Scope: deals.write — Deals erstellen, bearbeiten, verschieben und archivieren
Erforderliche Funktion: pipeline

Senden Sie einen Idempotency-Key mit, dann erzeugt ein erneuter Versuch nach einem Timeout keinen doppelten Datensatz.

Pfadparameter

Name	Typ	Beschreibung
`deal` erforderlich	string (uuid)	Die ID (UUID) des Deals.

Beispielanfrage

cURL

curl -X POST "https://app.klantly.com/api/v1/deals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/unarchive" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Idempotency-Key: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f"

PHP

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('POST', 'deals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/unarchive', [
    'headers' => [
        'Idempotency-Key' => '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];

JavaScript

const response = await fetch('https://app.klantly.com/api/v1/deals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/unarchive', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Idempotency-Key': '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
  },
});

const { data } = await response.json();

Python

import os

import requests

response = requests.post(
    "https://app.klantly.com/api/v1/deals/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/unarchive",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
        "Idempotency-Key": "6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    },
)
data = response.json()["data"]

Antwort 200

Beispielantwort

{
  "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"
  }
}

Mögliche Fehler

403 insufficient_scope — Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.
404 not_found — Nicht gefunden.
422 idempotency_key_reused — Dieser Idempotency-Key wurde bereits für eine andere Anfrage verwendet.
409 idempotency_in_progress — Eine Anfrage mit diesem Idempotency-Key wird noch verarbeitet.

Zusätzlich kann jeder Endpunkt die allgemeinen Fehler zurückgeben, etwa einen ungültigen Schlüssel oder ein erreichtes Limit. Alle Fehlercodes ansehen.

Das Objekt

Alle Felder sind immer vorhanden; ein Feld ohne Wert ist null.

Feld	Typ	Beschreibung
`object`	string	Immer „deal“.
`id`	string (uuid)	Eindeutige ID (UUID).
`title`	string	Titel des Deals.
`description`	string	Beschreibung. kann leer sein (null)
`status`	string	open, won (gewonnen) oder lost (verloren); ergibt sich aus der Phase. einer von: open, won, lost
`value`	string	Wert als Text mit zwei Dezimalstellen, zum Beispiel „8450.00“. Beim Erstellen und Bearbeiten dürfen Sie auch eine Zahl senden.
`currency`	string	Immer „EUR“.
`value_source`	string	quotes: Der Wert ergibt sich aus den verknüpften Angeboten; manual: von Hand festgelegt. einer von: quotes, manual
`stage`	object	Die Phase, in der der Deal steht; die Namen stehen in Pipeline-Phasen auflisten. kann leer sein (null)
`stage.object`	string	Immer „pipeline_stage“.
`stage.id`	string	ID der Phase.
`customer_id`	string (uuid)	Der Kunde des Deals. kann leer sein (null)
`assigned_user_id`	string	Der Benutzer, der den Deal betreut, oder null. kann leer sein (null)
`source`	string	Woher der Deal stammt; über die API ist das api. kann leer sein (null)
`lost_reason`	string	Warum der Deal verloren wurde, oder null. kann leer sein (null)
`is_archived`	boolean	Archiviert: nicht mehr auf dem Board.
`stage_changed_at`	string (date-time)	Wann der Deal zuletzt die Phase gewechselt hat. kann leer sein (null)
`won_at`	string (date-time)	Wann der Deal gewonnen wurde. kann leer sein (null)
`lost_at`	string (date-time)	Wann der Deal verloren wurde. kann leer sein (null)
`archived_at`	string (date-time)	Wann der Deal archiviert wurde. kann leer sein (null)
`created_at`	string (date-time)	Erstellt am (UTC).
`updated_at`	string (date-time)	Zuletzt geändert am (UTC).

Endpunkte

Deals auflisten#

Query-Parameter

Beispielanfrage

Antwort 200

Mögliche Fehler

Deal abrufen#

Pfadparameter

Beispielanfrage

Antwort 200

Mögliche Fehler

Deal erstellen#

Body (JSON)

Beispielanfrage

Antwort 201

Mögliche Fehler

Deal bearbeiten#

Pfadparameter

Body (JSON)

Beispielanfrage

Antwort 200

Mögliche Fehler

Deal verschieben#

Pfadparameter

Body (JSON)

Beispielanfrage

Antwort 200

Mögliche Fehler

Deal gewinnen#

Pfadparameter

Beispielanfrage

Antwort 200

Mögliche Fehler

Deal verlieren#

Pfadparameter

Body (JSON)

Beispielanfrage

Antwort 200

Mögliche Fehler

Deal archivieren#

Pfadparameter

Beispielanfrage

Antwort 200

Mögliche Fehler

Deal wiederherstellen#

Pfadparameter

Beispielanfrage

Antwort 200

Mögliche Fehler

Das Objekt#

Deals auflisten

Deal abrufen

Deal erstellen

Deal bearbeiten

Deal verschieben

Deal gewinnen

Deal verlieren

Deal archivieren

Deal wiederherstellen

Das Objekt