Deals

Deals opvragen

GET /api/v1/deals

Een lijst van deals, nieuwste eerst. Gearchiveerde deals staan er standaard niet in; gebruik daarvoor filter[archived]. Filter op status, fase, klant, eigenaar of wijzigingsdatum.

Scope: deals.read — Deals en pipelinefasen lezen
Vereiste functie: pipeline

Queryparameters

Naam	Type	Omschrijving
`limit`	integer	Aantal resultaten per pagina. van 1 tot 100 · standaard: 50
`cursor`	string	De next_cursor of prev_cursor uit meta van het vorige antwoord.
`sort`	string	Sortering op created_at, updated_at of stage_changed_at; een min-teken ervoor is aflopend. een van: -created_at, created_at, -updated_at, updated_at, -stage_changed_at, stage_changed_at · standaard: -created_at
`filter[status]`	string	Alleen open, gewonnen of verloren deals. een van: open, won, lost
`filter[stage_id]`	integer	Alleen deals in deze fase (de id uit Pipelinefasen opvragen).
`filter[customer_id]`	string (uuid)	Alleen deals van deze klant.
`filter[assigned_user_id]`	integer	Alleen deals van deze gebruiker.
`filter[archived]`	string	false (standaard) toont alleen deals op het bord, true alleen gearchiveerde, all allebei. een van: false, true, all · standaard: false
`filter[updated_since]`	string (date-time)	Alleen wat sinds dit tijdstip is gewijzigd: ISO 8601 mét tijdzone, bijvoorbeeld 2026-09-14T10:15:00Z. Handig om te synchroniseren.

Voorbeeldverzoek

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"]

Antwoord 200

Het antwoord is een lijst met cursorpaginering: data bevat de objecten, meta de paginering.

Voorbeeldantwoord

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

Mogelijke fouten

403 insufficient_scope — Deze API-sleutel heeft geen toegang tot deze actie.
422 validation_failed — De invoer is ongeldig.

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Deal ophalen

GET /api/v1/deals/{deal}

Eén deal op id. Het antwoord bevat een ETag die je bij bijwerken in If-Match kunt meesturen.

Scope: deals.read — Deals en pipelinefasen lezen
Vereiste functie: pipeline

Padparameters

Naam	Type	Omschrijving
`deal` verplicht	string (uuid)	De id (UUID) van de deal.

Voorbeeldverzoek

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"]

Antwoord 200

Voorbeeldantwoord

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

Mogelijke fouten

403 insufficient_scope — Deze API-sleutel heeft geen toegang tot deze actie.
404 not_found — Niet gevonden.

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Deal aanmaken

POST /api/v1/deals

Zet een klant op het pipelinebord. Een klant kan maar één open deal tegelijk hebben: heeft hij er al een, dan volgt 409 met de id van die deal in deal_id. Zonder stage_id komt de deal in de standaardfase. Stuur je value mee, dan houdt Klantly dat bedrag vast in plaats van het uit de offertes te berekenen.

Scope: deals.write — Deals aanmaken, wijzigen, verplaatsen en archiveren
Vereiste functie: pipeline

Stuur een Idempotency-Key mee, dan maakt een nieuwe poging na een time-out geen dubbel record.

Body (JSON)

Veld	Type	Omschrijving
`customer_id` verplicht	string (uuid)	De klant van de deal.
`title` optioneel	string	Titel van de deal. kan leeg zijn (null) · maximaal 255 tekens
`description` optioneel	string	Omschrijving. kan leeg zijn (null) · maximaal 10000 tekens
`value` optioneel	number	Waarde als tekst met twee decimalen, bijvoorbeeld "8450.00". Bij aanmaken en bijwerken mag je ook een getal sturen. kan leeg zijn (null) · van 0 tot 99999999
`stage_id` optioneel	integer	De fase waar de deal in komt. Zonder stage_id: de standaardfase. kan leeg zijn (null)
`assigned_user_id` optioneel	integer	De gebruiker die de deal behandelt, of null. kan leeg zijn (null)

Voorbeeldverzoek

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"]

Antwoord 201

Voorbeeldantwoord

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

Mogelijke fouten

403 insufficient_scope — Deze API-sleutel heeft geen toegang tot deze actie.
422 validation_failed — De invoer is ongeldig.
422 unknown_field — De invoer bevat een onbekend veld.
415 unsupported_media_type — Dit formaat wordt niet ondersteund.
413 payload_too_large — De body van het verzoek is te groot.
409 conflict — Dit botst met de huidige toestand.
422 idempotency_key_reused — Deze Idempotency-Key is al gebruikt voor een ander verzoek.
409 idempotency_in_progress — Een verzoek met deze Idempotency-Key is nog bezig.

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Deal bijwerken

PATCH /api/v1/deals/{deal}

Wijzigt alleen de velden die je meestuurt. De fase verander je met verplaatsen, winnen of verliezen. Een meegestuurde value zet value_source op manual.

Scope: deals.write — Deals aanmaken, wijzigen, verplaatsen en archiveren
Vereiste functie: pipeline

Stuur de ETag mee in If-Match, dan overschrijf je nooit per ongeluk een nieuwere versie.

Padparameters

Naam	Type	Omschrijving
`deal` verplicht	string (uuid)	De id (UUID) van de deal.

Body (JSON)

Veld	Type	Omschrijving
`title` optioneel	string	Titel van de deal. maximaal 255 tekens
`description` optioneel	string	Omschrijving. kan leeg zijn (null) · maximaal 10000 tekens
`value` optioneel	number	Waarde als tekst met twee decimalen, bijvoorbeeld "8450.00". Bij aanmaken en bijwerken mag je ook een getal sturen. van 0 tot 99999999
`assigned_user_id` optioneel	integer	De gebruiker die de deal behandelt, of null. kan leeg zijn (null)

Voorbeeldverzoek

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"]

Antwoord 200

Voorbeeldantwoord

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

Mogelijke fouten

403 insufficient_scope — Deze API-sleutel heeft geen toegang tot deze actie.
422 validation_failed — De invoer is ongeldig.
422 unknown_field — De invoer bevat een onbekend veld.
415 unsupported_media_type — Dit formaat wordt niet ondersteund.
413 payload_too_large — De body van het verzoek is te groot.
404 not_found — Niet gevonden.
412 precondition_failed — Het record is intussen gewijzigd.

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Deal verplaatsen

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

Verplaatst de deal naar een andere fase, precies zoals slepen op het bord. Is dat een gewonnen of verloren fase, dan wordt de deal ook gewonnen of verloren.

Scope: deals.write — Deals aanmaken, wijzigen, verplaatsen en archiveren
Vereiste functie: pipeline

Stuur een Idempotency-Key mee, dan maakt een nieuwe poging na een time-out geen dubbel record.

Padparameters

Naam	Type	Omschrijving
`deal` verplicht	string (uuid)	De id (UUID) van de deal.

Body (JSON)

Veld	Type	Omschrijving
`stage_id` verplicht	integer	De id van de fase waar de deal naartoe gaat (uit Pipelinefasen opvragen).
`notes` optioneel	string	Optionele toelichting; wordt met de fasewissel in de geschiedenis van de deal bewaard. kan leeg zijn (null) · maximaal 500 tekens

Voorbeeldverzoek

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"]

Antwoord 200

Voorbeeldantwoord

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

Mogelijke fouten

403 insufficient_scope — Deze API-sleutel heeft geen toegang tot deze actie.
422 validation_failed — De invoer is ongeldig.
422 unknown_field — De invoer bevat een onbekend veld.
415 unsupported_media_type — Dit formaat wordt niet ondersteund.
413 payload_too_large — De body van het verzoek is te groot.
404 not_found — Niet gevonden.
422 idempotency_key_reused — Deze Idempotency-Key is al gebruikt voor een ander verzoek.
409 idempotency_in_progress — Een verzoek met deze Idempotency-Key is nog bezig.

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Deal winnen

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

Verplaatst de deal naar de fase die je bedrijf als gewonnen heeft ingesteld. Is hij al gewonnen, dan verandert er niets.

Scope: deals.write — Deals aanmaken, wijzigen, verplaatsen en archiveren
Vereiste functie: pipeline

Stuur een Idempotency-Key mee, dan maakt een nieuwe poging na een time-out geen dubbel record.

Padparameters

Naam	Type	Omschrijving
`deal` verplicht	string (uuid)	De id (UUID) van de deal.

Voorbeeldverzoek

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"]

Antwoord 200

Voorbeeldantwoord

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

Mogelijke fouten

403 insufficient_scope — Deze API-sleutel heeft geen toegang tot deze actie.
404 not_found — Niet gevonden.
409 invalid_state_transition — Deze actie kan niet in de huidige status.
422 idempotency_key_reused — Deze Idempotency-Key is al gebruikt voor een ander verzoek.
409 idempotency_in_progress — Een verzoek met deze Idempotency-Key is nog bezig.

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Deal verliezen

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

Verplaatst de deal naar de fase die je bedrijf als verloren heeft ingesteld, met optioneel een reden.

Scope: deals.write — Deals aanmaken, wijzigen, verplaatsen en archiveren
Vereiste functie: pipeline

Stuur een Idempotency-Key mee, dan maakt een nieuwe poging na een time-out geen dubbel record.

Padparameters

Naam	Type	Omschrijving
`deal` verplicht	string (uuid)	De id (UUID) van de deal.

Body (JSON)

Veld	Type	Omschrijving
`lost_reason` optioneel	string	Waarom de deal verloren is, of null. kan leeg zijn (null) · maximaal 255 tekens

Voorbeeldverzoek

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"]

Antwoord 200

Voorbeeldantwoord

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

Mogelijke fouten

403 insufficient_scope — Deze API-sleutel heeft geen toegang tot deze actie.
422 validation_failed — De invoer is ongeldig.
422 unknown_field — De invoer bevat een onbekend veld.
415 unsupported_media_type — Dit formaat wordt niet ondersteund.
413 payload_too_large — De body van het verzoek is te groot.
404 not_found — Niet gevonden.
409 invalid_state_transition — Deze actie kan niet in de huidige status.
422 idempotency_key_reused — Deze Idempotency-Key is al gebruikt voor een ander verzoek.
409 idempotency_in_progress — Een verzoek met deze Idempotency-Key is nog bezig.

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Deal archiveren

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

Haalt de deal van het bord zonder hem te verwijderen. Deals verwijderen kan niet via de API.

Scope: deals.write — Deals aanmaken, wijzigen, verplaatsen en archiveren
Vereiste functie: pipeline

Stuur een Idempotency-Key mee, dan maakt een nieuwe poging na een time-out geen dubbel record.

Padparameters

Naam	Type	Omschrijving
`deal` verplicht	string (uuid)	De id (UUID) van de deal.

Voorbeeldverzoek

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"]

Antwoord 200

Voorbeeldantwoord

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

Mogelijke fouten

403 insufficient_scope — Deze API-sleutel heeft geen toegang tot deze actie.
404 not_found — Niet gevonden.
422 idempotency_key_reused — Deze Idempotency-Key is al gebruikt voor een ander verzoek.
409 idempotency_in_progress — Een verzoek met deze Idempotency-Key is nog bezig.

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Deal terugzetten

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

Zet een gearchiveerde deal terug op het bord.

Scope: deals.write — Deals aanmaken, wijzigen, verplaatsen en archiveren
Vereiste functie: pipeline

Stuur een Idempotency-Key mee, dan maakt een nieuwe poging na een time-out geen dubbel record.

Padparameters

Naam	Type	Omschrijving
`deal` verplicht	string (uuid)	De id (UUID) van de deal.

Voorbeeldverzoek

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"]

Antwoord 200

Voorbeeldantwoord

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

Mogelijke fouten

403 insufficient_scope — Deze API-sleutel heeft geen toegang tot deze actie.
404 not_found — Niet gevonden.
422 idempotency_key_reused — Deze Idempotency-Key is al gebruikt voor een ander verzoek.
409 idempotency_in_progress — Een verzoek met deze Idempotency-Key is nog bezig.

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Het object

Alle velden zijn altijd aanwezig; een veld zonder waarde is null.

Veld	Type	Omschrijving
`object`	string	Altijd "deal".
`id`	string (uuid)	Unieke id (UUID).
`title`	string	Titel van de deal.
`description`	string	Omschrijving. kan leeg zijn (null)
`status`	string	open, won (gewonnen) of lost (verloren); volgt uit de fase. een van: open, won, lost
`value`	string	Waarde als tekst met twee decimalen, bijvoorbeeld "8450.00". Bij aanmaken en bijwerken mag je ook een getal sturen.
`currency`	string	Altijd "EUR".
`value_source`	string	quotes: de waarde volgt uit de gekoppelde offertes; manual: met de hand ingesteld. een van: quotes, manual
`stage`	object	De fase waar de deal in staat; de namen staan in Pipelinefasen opvragen. kan leeg zijn (null)
`stage.object`	string	Altijd "pipeline_stage".
`stage.id`	string	Id van de fase.
`customer_id`	string (uuid)	De klant van de deal. kan leeg zijn (null)
`assigned_user_id`	string	De gebruiker die de deal behandelt, of null. kan leeg zijn (null)
`source`	string	Waar de deal vandaan komt; via de API is dat api. kan leeg zijn (null)
`lost_reason`	string	Waarom de deal verloren is, of null. kan leeg zijn (null)
`is_archived`	boolean	Gearchiveerd: staat niet meer op het bord.
`stage_changed_at`	string (date-time)	Wanneer de deal voor het laatst van fase wisselde. kan leeg zijn (null)
`won_at`	string (date-time)	Wanneer de deal gewonnen werd. kan leeg zijn (null)
`lost_at`	string (date-time)	Wanneer de deal verloren werd. kan leeg zijn (null)
`archived_at`	string (date-time)	Wanneer de deal gearchiveerd werd. kan leeg zijn (null)
`created_at`	string (date-time)	Aangemaakt op (UTC).
`updated_at`	string (date-time)	Laatst gewijzigd op (UTC).

Endpoints

Deals opvragen#

Queryparameters

Voorbeeldverzoek

Antwoord 200

Mogelijke fouten

Deal ophalen#

Padparameters

Voorbeeldverzoek

Antwoord 200

Mogelijke fouten

Deal aanmaken#

Body (JSON)

Voorbeeldverzoek

Antwoord 201

Mogelijke fouten

Deal bijwerken#

Padparameters

Body (JSON)

Voorbeeldverzoek

Antwoord 200

Mogelijke fouten

Deal verplaatsen#

Padparameters

Body (JSON)

Voorbeeldverzoek

Antwoord 200

Mogelijke fouten

Deal winnen#

Padparameters

Voorbeeldverzoek

Antwoord 200

Mogelijke fouten

Deal verliezen#

Padparameters

Body (JSON)

Voorbeeldverzoek

Antwoord 200

Mogelijke fouten

Deal archiveren#

Padparameters

Voorbeeldverzoek

Antwoord 200

Mogelijke fouten

Deal terugzetten#

Padparameters

Voorbeeldverzoek

Antwoord 200

Mogelijke fouten

Het object#

Deals opvragen

Deal ophalen

Deal aanmaken

Deal bijwerken

Deal verplaatsen

Deal winnen

Deal verliezen

Deal archiveren

Deal terugzetten

Het object