Klantly Developers

Paginierung, Filter und Synchronisieren

Listen mit einem Cursor durchblättern, filtern und sortieren und Änderungen synchron halten.

Listen

Eine Listenantwort hat data (die Objekte) und meta (die Paginierung):

JSON
{
  "data": [],
  "meta": {
    "limit": 50,
    "next_cursor": "eyJpdiI6ImYvZUgxaFR5bVRHSTBXeDFGYmZrZWc9PSIsInZhbHVl…",
    "prev_cursor": null
  }
}

Blättern mit einem Cursor

Rufen Sie die nächste Seite mit dem next_cursor aus der vorherigen Antwort ab:

cURL
curl "https://app.klantly.com/api/v1/customers?limit=100&cursor=eyJpdiI6ImYvZUgxaFR5bVRHSTBXeDFGYmZrZWc9PSIsInZhbHVl…" \
  -H "Authorization: Bearer $KLANTLY_API_KEY"

Ist next_cursor gleich null, sind Sie auf der letzten Seite. Ein Cursor zeigt auf eine Position in der Sortierung, nicht auf eine Seitenzahl: Datensätze, die zwischendurch hinzukommen, verschieben nichts. Sortieren Sie nach updated_at, kann ein Datensatz, der sich während des Blätterns ändert, weiter hinten noch einmal erscheinen; entfernen Sie Duplikate daher anhand der id. Ein Cursor gehört zu einer Sortierung: Verwenden Sie ihn nicht mit einem anderen sort. limit reicht von 1 bis 100; Standard ist 50. Der Cursor ist verschlüsselt: Verwenden Sie ihn so, wie Sie ihn erhalten, und bauen Sie ihn nie selbst. Ein Cursor ist einige hundert Zeichen lang und verschlüsselt; speichern Sie ihn als freien Text und geben Sie ihn unverändert zurück.

Filtern und Suchen

Filter stehen in filter[...], zum Beispiel filter[status]=lead oder filter[email]=jan@example.com. Bei Kunden durchsuchen Sie mit q mehrere Felder gleichzeitig: Name, E-Mail-Adresse, Firmenname und Telefonnummer. Welche Filter es gibt, steht pro Endpunkt in der API-Referenz. Ein unbekannter Filter ergibt einen Validierungsfehler.

Sortieren

sort=created_at sortiert aufsteigend, sort=-created_at absteigend. Überall ist absteigend nach Erstellungsdatum der Standard; nur die Nachrichten einer Unterhaltung laufen von alt nach neu. Sie können created_at oder updated_at wählen; bei Events und bei den Nachrichten einer Unterhaltung nur created_at. Welche Felder Sie wählen können und was der Standard ist, steht pro Endpunkt in der API-Referenz.

Synchronisieren

Um Ihr eigenes System aktuell zu halten, rufen Sie regelmäßig ab, was sich geändert hat:

  1. Merken Sie sich den Zeitpunkt Ihrer vorherigen Synchronisierung.
  2. Rufen Sie filter[updated_since]=<dieser Zeitpunkt>&sort=updated_at ab und blättern Sie alle Seiten durch.
  3. Speichern Sie den neuen Zeitpunkt.

Tipp

Planen Sie eine kleine Überlappung ein, zum Beispiel eine Minute, damit Ihnen keine Änderung entgeht, die genau während Ihres vorherigen Durchlaufs erfolgte.

Untergeordnete Objekte zählen nicht immer mit: Eine Zahlung, ein Anhang oder eine Nachricht aktualisiert updated_at der Rechnung, des Angebots oder der Unterhaltung, eine Notiz zu einem Kunden oder Deal jedoch nicht. Notizen verfolgen Sie mit den Events note.created, note.updated und note.deleted.

Eine Löschung sehen Sie nie über filter[updated_since] — der Datensatz verschwindet einfach aus der Liste. Hören Sie dafür auf die *.deleted-Events.

Events kennen kein Änderungsdatum: Dort rufen Sie mit filter[created_since] ab, was seit einem Zeitpunkt geschehen ist. Siehe Webhooks, um verpasste Nachrichten nachzuholen.

Zuletzt aktualisiert am 21. September 2026