Bewertungen

Bewertungen abrufen

GET /api/v1/reviews

Eine Liste der Bewertungen, neueste zuerst. Filtern nach Status, Quelle, Note, Kunde oder Änderungsdatum. Mit filter[status]=published erhalten Sie, was öffentlich steht.

Scope: reviews.read — Bewertungen und Bewertungsanfragen lesen
Erforderliche Funktion: reviews

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 oder updated_at; ein Minuszeichen davor sortiert absteigend. einer von: -reviewed_at, reviewed_at, -created_at, created_at, -updated_at, updated_at · Standard: -reviewed_at
`filter[status]`	string	Nur Bewertungen mit diesem Status: published (öffentlich) oder hidden (verborgen). einer von: published, hidden
`filter[source]`	string	Nur Bewertungen aus dieser Quelle: request (über eine Bewertungsanfrage), manual (selbst erfasst), configurator oder google. einer von: request, manual, configurator, google
`filter[rating]`	integer	Nur Bewertungen mit dieser Note (1 bis 5). von 1 bis 5
`filter[customer_id]`	string (uuid)	Nur was zu diesem Kunden 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.

Beispielanfrage

cURL

curl "https://app.klantly.com/api/v1/reviews?filter[status]=published&sort=-reviewed_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', 'reviews', [
    'query' => [
        'filter[status]' => 'published',
        'sort' => '-reviewed_at',
    ],
]);

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

JavaScript

const response = await fetch('https://app.klantly.com/api/v1/reviews?filter[status]=published&sort=-reviewed_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/reviews",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
    params={
        "filter[status]": "published",
        "sort": "-reviewed_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": "review",
      "id": "9d3f9c34-8d9e-4f01-9123-c4d5e6f7a8b3",
      "status": "published",
      "hidden_reason": null,
      "source": "request",
      "rating": 5,
      "comment": "Strakke veranda, netjes geplaatst en goed opgeruimd.",
      "author": {
        "name": "Jan de Vries",
        "city": "Utrecht"
      },
      "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
      "language": "nl",
      "is_verified": true,
      "consent_publish": true,
      "reply": null,
      "replied_at": null,
      "reviewed_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.

Bewertung abrufen

GET /api/v1/reviews/{review}

Eine Bewertung anhand der ID, mit Note, Text, Verfasser und der Antwort des Unternehmens.

Scope: reviews.read — Bewertungen und Bewertungsanfragen lesen
Erforderliche Funktion: reviews

Pfadparameter

Name	Typ	Beschreibung
`review` erforderlich	string (uuid)	Die ID (UUID) der Bewertung.

Beispielanfrage

cURL

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

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

JavaScript

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

Antwort 200

Beispielantwort

{
  "data": {
    "object": "review",
    "id": "9d3f9c34-8d9e-4f01-9123-c4d5e6f7a8b3",
    "status": "published",
    "hidden_reason": null,
    "source": "request",
    "rating": 5,
    "comment": "Strakke veranda, netjes geplaatst en goed opgeruimd.",
    "author": {
      "name": "Jan de Vries",
      "city": "Utrecht"
    },
    "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    "language": "nl",
    "is_verified": true,
    "consent_publish": true,
    "reply": null,
    "replied_at": null,
    "reviewed_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.

Bewertungsanfragen abrufen

GET /api/v1/review-requests

Die gesendeten und offenen Bewertungsanfragen, neueste zuerst, mit Status und dem Link für den Kunden.

Scope: reviews.read — Bewertungen und Bewertungsanfragen lesen
Erforderliche Funktion: reviews

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.
`filter[status]`	string	Nur Anfragen mit diesem Status: scheduled, sent, opened, completed, failed, cancelled oder expired. einer von: scheduled, sent, opened, completed, failed, cancelled, expired
`filter[customer_id]`	string (uuid)	Nur was zu diesem Kunden 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.

Beispielanfrage

cURL

curl "https://app.klantly.com/api/v1/review-requests" \
  -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', 'review-requests');

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

JavaScript

const response = await fetch('https://app.klantly.com/api/v1/review-requests', {
  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/review-requests",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
)
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": "review_request",
      "id": "9d3f9d45-9e0f-4012-a234-d5e6f7a8b9c4",
      "status": "sent",
      "channel": "email",
      "trigger": "manual",
      "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
      "recipient": {
        "name": "Jan de Vries",
        "email": "jan@example.com",
        "phone": null
      },
      "language": "nl",
      "url": "https://app.klantly.com/review/Xk2p9Qm4Rt7vB1nC8dE5fG3hJ6kL0mN2pQ4rS7tU",
      "review_id": null,
      "scheduled_at": null,
      "sent_at": null,
      "opened_at": null,
      "completed_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.

Bewertungsanfrage senden

POST /api/v1/review-requests

Bittet einen Kunden um eine Bewertung. Mit channel=email oder whatsapp sendet Klantly die Nachricht mit der Vorlage des Unternehmens; mit channel=link erstellen Sie nur den Link und teilen ihn selbst. Geben Sie customer_id an, oder name plus email oder phone. Dieselben Regeln wie im Bildschirm: keine zweite offene Anfrage an denselben Kunden, die Abkühlzeit des Unternehmens und niemand, der sich abgemeldet hat — sonst folgt 409 conflict.

Scope: reviews.write — Bewertungsanfragen an Kunden senden (eine Bewertung selbst anlegen ist nicht möglich)
Erforderliche Funktion: reviews

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

Body (JSON)

Feld	Typ	Beschreibung
`customer_id` optional	string (uuid)	Der Kunde, der die Anfrage erhält.
`name` optional	string	Name des Empfängers. Erforderlich, wenn Sie keine customer_id angeben. höchstens 120 Zeichen
`email` optional	string (email)	E-Mail-Adresse des Empfängers. Erforderlich bei channel=email. höchstens 255 Zeichen
`phone` optional	string	Telefonnummer des Empfängers. Erforderlich bei channel=whatsapp. höchstens 50 Zeichen
`channel` optional	string	Wie die Anfrage den Kunden erreicht: email, whatsapp oder link (dann sendet Klantly nichts). einer von: email, whatsapp, link
`language` optional	string	Die Sprache der Nachricht an den Kunden. einer von: nl, en, de, fr

Beispielanfrage

cURL

curl -X POST "https://app.klantly.com/api/v1/review-requests" \
  -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",
  "channel": "email"
}'

PHP

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

$response = $client->request('POST', 'review-requests', [
    'headers' => [
        'Idempotency-Key' => '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
    ],
    'json' => [
        'customer_id' => '9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70',
        'channel' => 'email',
    ],
]);

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

JavaScript

const response = await fetch('https://app.klantly.com/api/v1/review-requests', {
  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",
  "channel": "email"
}),
});

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

Python

import os

import requests

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

Antwort 201

Beispielantwort

{
  "data": {
    "object": "review_request",
    "id": "9d3f9d45-9e0f-4012-a234-d5e6f7a8b9c4",
    "status": "sent",
    "channel": "email",
    "trigger": "manual",
    "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    "recipient": {
      "name": "Jan de Vries",
      "email": "jan@example.com",
      "phone": null
    },
    "language": "nl",
    "url": "https://app.klantly.com/review/Xk2p9Qm4Rt7vB1nC8dE5fG3hJ6kL0mN2pQ4rS7tU",
    "review_id": null,
    "scheduled_at": null,
    "sent_at": null,
    "opened_at": null,
    "completed_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.

Das Objekt

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

Feld	Typ	Beschreibung
`object`	string	Immer "review".
`id`	string (uuid)	ID der Bewertung.
`status`	string	published (öffentlich) oder hidden (verborgen). einer von: published, hidden
`hidden_reason`	string	Warum die Bewertung verborgen ist, falls sie es ist. kann leer sein (null) · einer von: spam, offensive, not_a_customer, privacy, duplicate, other
`source`	string	Woher die Bewertung kommt: request, manual, configurator oder google. einer von: request, manual, configurator, google
`rating`	integer	Die Note, 1 bis 5. von 1 bis 5
`comment`	string	Was der Kunde geschrieben hat. kann leer sein (null)
`author`	object	Der Verfasser, wie er öffentlich gezeigt wird.
`author.name`	string	Name des Verfassers. kann leer sein (null)
`author.city`	string	Wohnort des Verfassers. kann leer sein (null)
`customer_id`	string (uuid)	Der Kunde, der die Bewertung geschrieben hat, sofern bekannt. kann leer sein (null)
`language`	string	Die Sprache, in der die Bewertung geschrieben wurde. kann leer sein (null) · einer von: nl, en, de, fr
`is_verified`	boolean	True, wenn die Bewertung über eine Bewertungsanfrage von Klantly eingegangen ist: Der Verfasser ist dann nachweislich Kunde.
`consent_publish`	boolean	Ob der Verfasser der Veröffentlichung zugestimmt hat.
`reply`	string	Die Antwort des Unternehmens auf diese Bewertung. kann leer sein (null)
`replied_at`	string (date-time)	Wann das Unternehmen geantwortet hat. kann leer sein (null)
`reviewed_at`	string (date-time)	Wann die Bewertung geschrieben wurde. kann leer sein (null)
`created_at`	string (date-time)	Wann die Bewertung in Klantly ankam.
`updated_at`	string (date-time)	Wann sich die Bewertung zuletzt geändert hat.

Endpunkte

Bewertungen abrufen#

Query-Parameter

Beispielanfrage

Antwort 200

Mögliche Fehler

Bewertung abrufen#

Pfadparameter

Beispielanfrage

Antwort 200

Mögliche Fehler

Bewertungsanfragen abrufen#

Query-Parameter

Beispielanfrage

Antwort 200

Mögliche Fehler

Bewertungsanfrage senden#

Body (JSON)

Beispielanfrage

Antwort 201

Mögliche Fehler

Das Objekt#

Bewertungen abrufen

Bewertung abrufen

Bewertungsanfragen abrufen

Bewertungsanfrage senden

Das Objekt