Klantly Developers

API-Referenz

Servicemeldungen

Kundenmeldungen (Störungen, Garantie, Reklamationen) mit Fotos: zum Beispiel aus einem Kundenportal erstellen, zuweisen und den Status verfolgen. Die eigentliche Arbeit mit Stunden und Abrechnung ist der Arbeitsauftrag. Einen Termin verknüpfen Sie mit appointment_id; das Unterschreiben, die Wahl des Termins selbst und das Umwandeln in einen Arbeitsauftrag erledigt ein Mensch in Klantly oder in der App.

Endpunkte

Servicemeldungen abrufen

GET /api/v1/services

Eine Liste der Meldungen, neueste zuerst, mit Fotos. Filtern Sie nach Status, Priorität, Kunde, Mitarbeiter, Angebot oder Änderungsdatum.

Scope
services.read — Servicemeldungen lesen, mit Name, Adresse und Kontaktdaten des Kunden
Erforderliche Funktion
work_orders

Query-Parameter

NameTypBeschreibung
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 Das Feld, nach dem sortiert wird; ein Minuszeichen davor bedeutet absteigend. Welche Felder Sie wählen können und was der Standard ist, steht bei diesem Parameter. einer von: -created_at, created_at, -updated_at, updated_at · Standard: -created_at
filter[status] string Nur Meldungen mit diesem Status. einer von: draft, planned, in_progress, completed, cancelled
filter[priority] string Nur Meldungen mit dieser Priorität. einer von: low, normal, high, urgent
filter[customer_id] string (uuid) Nur was zu diesem Kunden gehört.
filter[assigned_user_id] string Nur was diesem Benutzer zugewiesen ist (die ID aus Benutzer auflisten).
filter[quote_id] string (uuid) Nur was zu diesem Angebot gehört.
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. Überlappen Sie Ihren vorherigen Zeitpunkt um einige Minuten, weil die Uhr Ihres Systems und die von Klantly nicht exakt gleich laufen und weil eine Änderung kurz nach Ihrem vorherigen Zeitpunkt sonst knapp außerhalb liegen würde. Die Grenze ist inklusiv: etwas, das genau zu diesem Zeitpunkt geändert wurde, zählt mit.

Beispielanfrage

cURL
curl "https://app.klantly.com/api/v1/services?filter[status]=planned&sort=-updated_at" \
  -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', 'services', [
    'query' => [
        'filter[status]' => 'planned',
        'sort' => '-updated_at',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/services?filter[status]=planned&sort=-updated_at', {
  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/services",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
    params={
        "filter[status]": "planned",
        "sort": "-updated_at"
    },
)
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": "service",
      "id": "9d3f8339-9ed1-4f6e-8dbc-c1dfe0f1a2bb",
      "number": "SV-2026-00042",
      "status": "planned",
      "priority": "high",
      "category": "malfunction",
      "title": "Lekkage bij de dakgoot",
      "location": null,
      "description": "Water loopt langs de gevel na regen.",
      "resolution": null,
      "customer_notes": null,
      "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
      "customer": {
        "type": "business",
        "name": "De Vries Bouw",
        "email": "jan@example.com",
        "phone": "+31 6 12345678",
        "address": "Dorpsstraat 1",
        "postal_code": "3511 AB",
        "city": "Utrecht",
        "country": "NL"
      },
      "quote_id": null,
      "appointment_id": null,
      "work_order_id": null,
      "assigned_user_id": "usr_0k3j9x21m4zq8p",
      "language": "nl",
      "reported_at": null,
      "scheduled_at": "2026-10-01T08:00:00Z",
      "started_at": null,
      "completed_at": null,
      "signature": {
        "is_signed": false,
        "signed_by_name": null,
        "signed_at": null
      },
      "photos": [],
      "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

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

Servicemeldung abrufen

GET /api/v1/services/{service}

Eine Meldung anhand der id, mit Fotos (samt Downloadlink) und dem Stand der Unterschrift.

Scope
services.read — Servicemeldungen lesen, mit Name, Adresse und Kontaktdaten des Kunden
Erforderliche Funktion
work_orders

Pfadparameter

NameTypBeschreibung
service erforderlich string (uuid) Die id (UUID) der Servicemeldung.

Beispielanfrage

cURL
curl "https://app.klantly.com/api/v1/services/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', 'services/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70');

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/services/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/services/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
)
data = response.json()["data"]

Antwort 200

Beispielantwort
{
  "data": {
    "object": "service",
    "id": "9d3f8339-9ed1-4f6e-8dbc-c1dfe0f1a2bb",
    "number": "SV-2026-00042",
    "status": "planned",
    "priority": "high",
    "category": "malfunction",
    "title": "Lekkage bij de dakgoot",
    "location": null,
    "description": "Water loopt langs de gevel na regen.",
    "resolution": null,
    "customer_notes": null,
    "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    "customer": {
      "type": "business",
      "name": "De Vries Bouw",
      "email": "jan@example.com",
      "phone": "+31 6 12345678",
      "address": "Dorpsstraat 1",
      "postal_code": "3511 AB",
      "city": "Utrecht",
      "country": "NL"
    },
    "quote_id": null,
    "appointment_id": null,
    "work_order_id": null,
    "assigned_user_id": "usr_0k3j9x21m4zq8p",
    "language": "nl",
    "reported_at": null,
    "scheduled_at": "2026-10-01T08:00:00Z",
    "started_at": null,
    "completed_at": null,
    "signature": {
      "is_signed": false,
      "signed_by_name": null,
      "signed_at": null
    },
    "photos": [],
    "created_at": "2026-09-14T10:15:00Z",
    "updated_at": "2026-09-14T10:15:00Z"
  }
}

Mögliche Fehler

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

Servicemeldung erstellen

POST /api/v1/services

Erstellt eine Meldung zu einem Kunden, als Entwurf oder eingeplant. Klantly vergibt eine Nummer aus einer eigenen Reihe (standardmäßig SV-Jahr-Nummer); Name, Adresse und Kontaktdaten stammen vom Kunden. Ohne reported_at ist das der Zeitpunkt der Erstellung.

Scope
services.write — Servicemeldungen erstellen und ändern, den Status anpassen und Fotos hinzufügen
Erforderliche Funktion
work_orders

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

Body (JSON)

FeldTypBeschreibung
customer_id erforderlich string (uuid) Der Kunde. Beim Erstellen erforderlich; Name, Adresse und Kontaktdaten stammen vom Kunden.
title erforderlich string Betreff der Meldung. Beim Erstellen erforderlich. höchstens 255 Zeichen
status optional string draft (Entwurf), planned (eingeplant), in_progress (in Bearbeitung), completed (abgeschlossen) oder cancelled (storniert). Beim Erstellen draft oder planned. einer von: draft, planned
category optional string Art der Meldung, zum Beispiel malfunction (Störung), warranty (Garantie), maintenance (Wartung), complaint (Reklamation), question oder other. Freier Text: ein Unternehmen darf eigene Arten verwenden. kann leer sein (null) · höchstens 64 Zeichen
priority optional string low, normal, high oder urgent. Standard ist normal. einer von: low, normal, high, urgent
location optional string Wo das Problem ist, wenn das nicht die Adresse des Kunden ist. kann leer sein (null) · höchstens 255 Zeichen
description optional string Das Problem, wie der Kunde es meldet. kann leer sein (null) · höchstens 20000 Zeichen
resolution optional string Was zur Behebung getan wurde. kann leer sein (null) · höchstens 20000 Zeichen
customer_notes optional string Anmerkungen für den Kunden. kann leer sein (null) · höchstens 20000 Zeichen
reported_at optional string (date-time) Wann die Meldung einging (UTC). Beim Erstellen leer bedeutet der Zeitpunkt der Erstellung. Bei Eingabe: ISO 8601 mit Zeitzone. kann leer sein (null)
scheduled_at optional string (date-time) Wann der Servicebesuch geplant ist (UTC). Bei Eingabe: ISO 8601 mit Zeitzone. kann leer sein (null)
assigned_user_id optional string Der Mitarbeiter, der die Meldung übernimmt, oder null. kann leer sein (null)
appointment_id optional string (uuid) Der Termin für den Servicebesuch, oder null. kann leer sein (null)
quote_id optional string (uuid) Das Angebot, zu dem die Meldung gehört, oder null. kann leer sein (null)
language optional string Sprache der Meldung: nl, en, de oder fr. einer von: nl, en, de, fr

Beispielanfrage

cURL
curl -X POST "https://app.klantly.com/api/v1/services" \
  -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": "Lekkage bij de dakgoot",
  "category": "malfunction",
  "priority": "high",
  "description": "Water loopt langs de gevel na regen."
}'
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('POST', 'services', [
    'headers' => [
        'Idempotency-Key' => '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
    ],
    'json' => [
        'customer_id' => '9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70',
        'title' => 'Lekkage bij de dakgoot',
        'category' => 'malfunction',
        'priority' => 'high',
        'description' => 'Water loopt langs de gevel na regen.',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/services', {
  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": "Lekkage bij de dakgoot",
  "category": "malfunction",
  "priority": "high",
  "description": "Water loopt langs de gevel na regen."
}),
});

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

import requests

response = requests.post(
    "https://app.klantly.com/api/v1/services",
    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": "Lekkage bij de dakgoot",
        "category": "malfunction",
        "priority": "high",
        "description": "Water loopt langs de gevel na regen."
    },
)
data = response.json()["data"]

Antwort 201

Beispielantwort
{
  "data": {
    "object": "service",
    "id": "9d3f8339-9ed1-4f6e-8dbc-c1dfe0f1a2bb",
    "number": "SV-2026-00042",
    "status": "planned",
    "priority": "high",
    "category": "malfunction",
    "title": "Lekkage bij de dakgoot",
    "location": null,
    "description": "Water loopt langs de gevel na regen.",
    "resolution": null,
    "customer_notes": null,
    "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    "customer": {
      "type": "business",
      "name": "De Vries Bouw",
      "email": "jan@example.com",
      "phone": "+31 6 12345678",
      "address": "Dorpsstraat 1",
      "postal_code": "3511 AB",
      "city": "Utrecht",
      "country": "NL"
    },
    "quote_id": null,
    "appointment_id": null,
    "work_order_id": null,
    "assigned_user_id": "usr_0k3j9x21m4zq8p",
    "language": "nl",
    "reported_at": null,
    "scheduled_at": "2026-10-01T08:00:00Z",
    "started_at": null,
    "completed_at": null,
    "signature": {
      "is_signed": false,
      "signed_by_name": null,
      "signed_at": null
    },
    "photos": [],
    "created_at": "2026-09-14T10:15:00Z",
    "updated_at": "2026-09-14T10:15:00Z"
  }
}

Mögliche Fehler

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

Servicemeldung aktualisieren

PATCH /api/v1/services/{service}

Ändert nur die Felder, die Sie mitsenden. Die Verknüpfung mit dem Arbeitsauftrag setzen Sie nicht selbst: sie entsteht, wenn Sie die Meldung in Klantly umwandeln.

Scope
services.write — Servicemeldungen erstellen und ändern, den Status anpassen und Fotos hinzufügen
Erforderliche Funktion
work_orders

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

Pfadparameter

NameTypBeschreibung
service erforderlich string (uuid) Die id (UUID) der Servicemeldung.

Body (JSON)

FeldTypBeschreibung
title optional string Betreff der Meldung. Beim Erstellen erforderlich. höchstens 255 Zeichen
category optional string Art der Meldung, zum Beispiel malfunction (Störung), warranty (Garantie), maintenance (Wartung), complaint (Reklamation), question oder other. Freier Text: ein Unternehmen darf eigene Arten verwenden. kann leer sein (null) · höchstens 64 Zeichen
priority optional string low, normal, high oder urgent. Standard ist normal. einer von: low, normal, high, urgent
location optional string Wo das Problem ist, wenn das nicht die Adresse des Kunden ist. kann leer sein (null) · höchstens 255 Zeichen
description optional string Das Problem, wie der Kunde es meldet. kann leer sein (null) · höchstens 20000 Zeichen
resolution optional string Was zur Behebung getan wurde. kann leer sein (null) · höchstens 20000 Zeichen
customer_notes optional string Anmerkungen für den Kunden. kann leer sein (null) · höchstens 20000 Zeichen
reported_at optional string (date-time) Wann die Meldung einging (UTC). Beim Erstellen leer bedeutet der Zeitpunkt der Erstellung. Bei Eingabe: ISO 8601 mit Zeitzone. kann leer sein (null)
scheduled_at optional string (date-time) Wann der Servicebesuch geplant ist (UTC). Bei Eingabe: ISO 8601 mit Zeitzone. kann leer sein (null)
assigned_user_id optional string Der Mitarbeiter, der die Meldung übernimmt, oder null. kann leer sein (null)
appointment_id optional string (uuid) Der Termin für den Servicebesuch, oder null. kann leer sein (null)
quote_id optional string (uuid) Das Angebot, zu dem die Meldung gehört, oder null. kann leer sein (null)
language optional string Sprache der Meldung: nl, en, de oder fr. einer von: nl, en, de, fr

Beispielanfrage

cURL
curl -X PATCH "https://app.klantly.com/api/v1/services/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "resolution": "Goot opnieuw afgekit en getest."
}'
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('PATCH', 'services/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70', [
    'json' => [
        'resolution' => 'Goot opnieuw afgekit en getest.',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/services/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "resolution": "Goot opnieuw afgekit en getest."
}),
});

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

import requests

response = requests.patch(
    "https://app.klantly.com/api/v1/services/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
    json={
        "resolution": "Goot opnieuw afgekit en getest."
    },
)
data = response.json()["data"]

Antwort 200

Beispielantwort
{
  "data": {
    "object": "service",
    "id": "9d3f8339-9ed1-4f6e-8dbc-c1dfe0f1a2bb",
    "number": "SV-2026-00042",
    "status": "planned",
    "priority": "high",
    "category": "malfunction",
    "title": "Lekkage bij de dakgoot",
    "location": null,
    "description": "Water loopt langs de gevel na regen.",
    "resolution": null,
    "customer_notes": null,
    "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    "customer": {
      "type": "business",
      "name": "De Vries Bouw",
      "email": "jan@example.com",
      "phone": "+31 6 12345678",
      "address": "Dorpsstraat 1",
      "postal_code": "3511 AB",
      "city": "Utrecht",
      "country": "NL"
    },
    "quote_id": null,
    "appointment_id": null,
    "work_order_id": null,
    "assigned_user_id": "usr_0k3j9x21m4zq8p",
    "language": "nl",
    "reported_at": null,
    "scheduled_at": "2026-10-01T08:00:00Z",
    "started_at": null,
    "completed_at": null,
    "signature": {
      "is_signed": false,
      "signed_by_name": null,
      "signed_at": null
    },
    "photos": [],
    "created_at": "2026-09-14T10:15:00Z",
    "updated_at": "2026-09-14T10:15:00Z"
  }
}

Mögliche Fehler

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

Status einer Servicemeldung ändern

POST /api/v1/services/{service}/status

Setzt die Meldung auf Entwurf, eingeplant, in Bearbeitung, abgeschlossen oder storniert. Bei in Bearbeitung und abgeschlossen werden started_at und completed_at gesetzt. Ist in den Arbeitsauftrags-Einstellungen „Unterschrift bei Service erforderlich“ aktiv, kann eine nicht unterschriebene Meldung nicht abgeschlossen werden (invalid_state_transition).

Scope
services.write — Servicemeldungen erstellen und ändern, den Status anpassen und Fotos hinzufügen
Erforderliche Funktion
work_orders

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

Pfadparameter

NameTypBeschreibung
service erforderlich string (uuid) Die id (UUID) der Servicemeldung.

Body (JSON)

FeldTypBeschreibung
status erforderlich string draft (Entwurf), planned (eingeplant), in_progress (in Bearbeitung), completed (abgeschlossen) oder cancelled (storniert). Beim Erstellen draft oder planned. einer von: draft, planned, in_progress, completed, cancelled

Beispielanfrage

cURL
curl -X POST "https://app.klantly.com/api/v1/services/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/status" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f" \
  -d '{
  "status": "completed"
}'
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

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

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/services/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/status', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
  },
  body: JSON.stringify({
  "status": "completed"
}),
});

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

import requests

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

Antwort 200

Beispielantwort
{
  "data": {
    "object": "service",
    "id": "9d3f8339-9ed1-4f6e-8dbc-c1dfe0f1a2bb",
    "number": "SV-2026-00042",
    "status": "planned",
    "priority": "high",
    "category": "malfunction",
    "title": "Lekkage bij de dakgoot",
    "location": null,
    "description": "Water loopt langs de gevel na regen.",
    "resolution": null,
    "customer_notes": null,
    "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    "customer": {
      "type": "business",
      "name": "De Vries Bouw",
      "email": "jan@example.com",
      "phone": "+31 6 12345678",
      "address": "Dorpsstraat 1",
      "postal_code": "3511 AB",
      "city": "Utrecht",
      "country": "NL"
    },
    "quote_id": null,
    "appointment_id": null,
    "work_order_id": null,
    "assigned_user_id": "usr_0k3j9x21m4zq8p",
    "language": "nl",
    "reported_at": null,
    "scheduled_at": "2026-10-01T08:00:00Z",
    "started_at": null,
    "completed_at": null,
    "signature": {
      "is_signed": false,
      "signed_by_name": null,
      "signed_at": null
    },
    "photos": [],
    "created_at": "2026-09-14T10:15:00Z",
    "updated_at": "2026-09-14T10:15:00Z"
  }
}

Mögliche Fehler

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

Servicemeldung löschen

DELETE /api/v1/services/{service}

Löscht die Meldung samt ihren Fotos.

Scope
services.delete — Servicemeldungen löschen
Erforderliche Funktion
work_orders

Pfadparameter

NameTypBeschreibung
service erforderlich string (uuid) Die id (UUID) der Servicemeldung.

Beispielanfrage

cURL
curl -X DELETE "https://app.klantly.com/api/v1/services/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('DELETE', 'services/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70');

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/services/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
  },
});

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

import requests

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

Antwort 200

Beispielantwort
{
  "data": {
    "object": "note",
    "id": "9d3f7b41-2d6f-4e8c-9b3a-4f5d6e7a8b92",
    "deleted": true
  }
}

Mögliche Fehler

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.

FeldTypBeschreibung
object string Immer "service".
id string (uuid) Eindeutige id (UUID).
number string Nummer der Meldung, zum Beispiel SV-2026-00042; Klantly vergibt sie aus einer eigenen Reihe neben den Arbeitsaufträgen.
status string draft (Entwurf), planned (eingeplant), in_progress (in Bearbeitung), completed (abgeschlossen) oder cancelled (storniert). Beim Erstellen draft oder planned. einer von: draft, planned, in_progress, completed, cancelled
priority string low, normal, high oder urgent. Standard ist normal. einer von: low, normal, high, urgent
category string Art der Meldung, zum Beispiel malfunction (Störung), warranty (Garantie), maintenance (Wartung), complaint (Reklamation), question oder other. Freier Text: ein Unternehmen darf eigene Arten verwenden. kann leer sein (null)
title string Betreff der Meldung. Beim Erstellen erforderlich.
location string Wo das Problem ist, wenn das nicht die Adresse des Kunden ist. kann leer sein (null)
description string Das Problem, wie der Kunde es meldet. kann leer sein (null)
resolution string Was zur Behebung getan wurde. kann leer sein (null)
customer_notes string Anmerkungen für den Kunden. kann leer sein (null)
customer_id string (uuid) Der Kunde. Beim Erstellen erforderlich; Name, Adresse und Kontaktdaten stammen vom Kunden. kann leer sein (null)
customer object Die Kundendaten auf der Meldung, wie sie beim Erstellen waren.
customer.type string individual (Privatperson) oder business (Unternehmen). kann leer sein (null)
customer.name string Name; bei einem Unternehmen der Firmenname. kann leer sein (null)
customer.email string E-Mail-Adresse. kann leer sein (null)
customer.phone string Telefonnummer. kann leer sein (null)
customer.address string Straße und Hausnummer. kann leer sein (null)
customer.postal_code string PLZ. kann leer sein (null)
customer.city string Ort. kann leer sein (null)
customer.country string Land. kann leer sein (null)
quote_id string (uuid) Das Angebot, zu dem die Meldung gehört, oder null. kann leer sein (null)
appointment_id string (uuid) Der Termin für den Servicebesuch, oder null. kann leer sein (null)
work_order_id string (uuid) Der Arbeitsauftrag, der aus dieser Meldung entstanden ist, oder null. Dieses Feld setzen Sie nicht selbst: es entsteht, wenn die Meldung in Klantly umgewandelt wird. kann leer sein (null)
assigned_user_id string Der Mitarbeiter, der die Meldung übernimmt, oder null. kann leer sein (null)
language string Sprache der Meldung: nl, en, de oder fr. einer von: nl, en, de, fr
reported_at string (date-time) Wann die Meldung einging (UTC). Beim Erstellen leer bedeutet der Zeitpunkt der Erstellung. Bei Eingabe: ISO 8601 mit Zeitzone. kann leer sein (null)
scheduled_at string (date-time) Wann der Servicebesuch geplant ist (UTC). Bei Eingabe: ISO 8601 mit Zeitzone. kann leer sein (null)
started_at string (date-time) Wann die Bearbeitung begann. kann leer sein (null)
completed_at string (date-time) Wann die Meldung abgeschlossen wurde. kann leer sein (null)
signature object Die Unterschrift des Kunden bei der Übergabe (nur die Daten, kein Bild).
signature.is_signed boolean Ist die Meldung unterschrieben.
signature.signed_by_name string Name des Unterzeichners. kann leer sein (null)
signature.signed_at string (date-time) Wann unterschrieben wurde. kann leer sein (null)
photos array<object> Die Fotos zur Meldung. Das Hochladen läuft über POST /services/{id}/photos.
photos.object string Immer "service_photo".
photos.id string (uuid) Id des Fotos.
photos.kind string issue (die Meldung), progress, completion (die Übergabe) oder other. kann leer sein (null) · einer von: issue, progress, completion, other
photos.caption string Bildunterschrift. kann leer sein (null)
photos.download_url string (uri) Ein signierter Link zum Foto, eine Viertelstunde gültig und ohne API-Schlüssel zu öffnen.
photos.created_at string (date-time) Wann das Foto hinzugefügt wurde (UTC).
created_at string (date-time) Wann die Meldung erstellt wurde (UTC).
updated_at string (date-time) Wann die Meldung zuletzt geändert wurde (UTC).