Klantly Developers

Paginering, filters en synchroniseren

Lijsten doorbladeren met een cursor, filteren en sorteren, en wijzigingen synchroniseren.

Lijsten

Een lijstantwoord heeft data (de objecten) en meta (de paginering):

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

Doorbladeren met een cursor

Vraag de volgende pagina op met de next_cursor uit het vorige antwoord:

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

Is next_cursor gelijk aan null, dan ben je op de laatste pagina. Een cursor wijst naar een positie in de sortering, niet naar een paginanummer: records die er tussendoor bijkomen, verschuiven niets. Sorteer je op updated_at, dan kan een record dat tijdens het bladeren wordt gewijzigd verderop nog een keer langskomen; ontdubbel daarom op id. Een cursor hoort bij één sortering: gebruik hem niet met een andere sort. limit loopt van 1 tot 100; de standaard is 50. De cursor is versleuteld: gebruik hem zoals je hem krijgt en bouw hem nooit zelf. Een cursor is enkele honderden tekens lang en versleuteld; bewaar hem als vrije tekst en geef hem onveranderd terug.

Filteren en zoeken

Filters staan in filter[...], bijvoorbeeld filter[status]=lead of filter[email]=jan@example.com. Bij klanten zoek je met q in meerdere velden tegelijk: naam, e-mailadres, bedrijfsnaam en telefoonnummer. Welke filters er zijn, staat per endpoint in de API-referentie. Een onbekend filter geeft een validatiefout.

Sorteren

sort=created_at sorteert oplopend, sort=-created_at aflopend. Overal is aflopend op aanmaakdatum de standaard; alleen de berichten van een gesprek staan juist op volgorde van oud naar nieuw. Je kunt kiezen uit created_at en updated_at; bij events en bij de berichten van een gesprek alleen created_at. Welke velden je kunt kiezen en wat de standaard is, staat per endpoint in de API-referentie.

Synchroniseren

Wil je je eigen systeem bijhouden, haal dan periodiek op wat er gewijzigd is:

  1. Onthoud het tijdstip van je vorige synchronisatie.
  2. Vraag filter[updated_since]=<dat tijdstip>&sort=updated_at op en blader alle pagina's door.
  3. Sla het nieuwe tijdstip op.

Tip

Neem een kleine overlap, bijvoorbeeld een minuut, zodat je geen wijziging mist die precies tijdens je vorige ronde plaatsvond.

Onderliggende objecten tellen niet altijd mee: een betaling, een bijlage of een bericht werkt updated_at van de factuur, offerte of het gesprek bij, maar een notitie bij een klant of deal niet. Notities houd je bij met de events note.created, note.updated en note.deleted.

Een verwijdering zie je nooit via filter[updated_since] — het record verdwijnt uit de lijst. Luister daarvoor naar de *.deleted-events.

Events kennen geen wijzigingsdatum: daar haal je met filter[created_since] op wat er sinds een tijdstip gebeurde. Zie Webhooks voor het inhalen van gemiste berichten.

Laatst bijgewerkt op 21 september 2026