Klantly Developers

Référence de l'API

Événements

Tout ce qui a changé au cours des 30 derniers jours, sous forme de liste. Pour rattraper des webhooks manqués, ou pour interroger l'API au lieu d'utiliser des webhooks.

Endpoints

Lister les événements

GET /api/v1/events

Les événements des 30 derniers jours, le plus récent en premier. Vous ne voyez que les événements portant sur des données que votre clé peut lire. Avec sort=created_at et filter[created_since], vous rattrapez les événements manqués dans l'ordre.

Scope
events.read — Récupérer les événements

Paramètres de requête

NomTypeDescription
limit integer Nombre de résultats par page. de 1 à 100 · par défaut : 50
cursor string Le next_cursor ou prev_cursor de meta dans la réponse précédente.
sort string created_at respecte l'ordre dans lequel tout s'est produit, -created_at (par défaut) affiche le plus récent en premier. l'une des valeurs : -created_at, created_at · par défaut : -created_at
filter[type] string Uniquement ces types d'événements, séparés par des virgules, par exemple customer.created,deal.won. au maximum 500 caractères
filter[created_since] string (date-time) Uniquement les événements à partir de ce moment : ISO 8601 avec fuseau horaire, par exemple 2026-09-14T10:15:00Z.

Exemple de requête

cURL
curl "https://app.klantly.com/api/v1/events?filter[type]=customer.created%2Cdeal.won&sort=created_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', 'events', [
    'query' => [
        'filter[type]' => 'customer.created,deal.won',
        'sort' => 'created_at',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/events?filter[type]=customer.created%2Cdeal.won&sort=created_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/events",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
    params={
        "filter[type]": "customer.created,deal.won",
        "sort": "created_at"
    },
)
data = response.json()["data"]

Réponse 200

La réponse est une liste avec pagination par curseur : data contient les objets, meta la pagination.

Exemple de réponse
{
  "data": [
    {
      "object": "event",
      "id": "evt_01j7zs1a2b3c4d5e6f7g8h9j0k",
      "type": "customer.created",
      "created_at": "2026-09-14T10:15:00Z",
      "data": {
        "object": {
          "object": "customer",
          "id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
          "type": "business",
          "status": "lead",
          "name": "Jan de Vries",
          "email": "jan@example.com",
          "phone": "+31 6 12345678",
          "company_name": "De Vries Bouw",
          "vat_number": "NL123456789B01",
          "coc_number": "12345678",
          "address": "Dorpsstraat 1",
          "postal_code": "3511 AB",
          "city": "Utrecht",
          "country": "NL",
          "email_unsubscribed": false,
          "converted_at": null,
          "last_activity_at": "2026-09-14T10:15:00Z",
          "created_at": "2026-09-14T10:15:00Z",
          "updated_at": "2026-09-14T10:15:00Z"
        }
      }
    }
  ],
  "meta": {
    "limit": 50,
    "next_cursor": "eyJpZCI6IjlkM2Y2YzFlIn0",
    "prev_cursor": null
  }
}

Erreurs possibles

En outre, chaque endpoint peut renvoyer les erreurs générales, comme une clé invalide ou une limite atteinte. Voir tous les codes d'erreur.

Récupérer un événement

GET /api/v1/events/{event}

Un événement par id, par exemple le webhook-id d'un message reçu.

Scope
events.read — Récupérer les événements

Paramètres de chemin

NomTypeDescription
event obligatoire string L'id de l'événement (evt_…).

Exemple de requête

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

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

Réponse 200

Exemple de réponse
{
  "data": {
    "object": "event",
    "id": "evt_01j7zs1a2b3c4d5e6f7g8h9j0k",
    "type": "customer.created",
    "created_at": "2026-09-14T10:15:00Z",
    "data": {
      "object": {
        "object": "customer",
        "id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
        "type": "business",
        "status": "lead",
        "name": "Jan de Vries",
        "email": "jan@example.com",
        "phone": "+31 6 12345678",
        "company_name": "De Vries Bouw",
        "vat_number": "NL123456789B01",
        "coc_number": "12345678",
        "address": "Dorpsstraat 1",
        "postal_code": "3511 AB",
        "city": "Utrecht",
        "country": "NL",
        "email_unsubscribed": false,
        "converted_at": null,
        "last_activity_at": "2026-09-14T10:15:00Z",
        "created_at": "2026-09-14T10:15:00Z",
        "updated_at": "2026-09-14T10:15:00Z"
      }
    }
  }
}

Erreurs possibles

En outre, chaque endpoint peut renvoyer les erreurs générales, comme une clé invalide ou une limite atteinte. Voir tous les codes d'erreur.

L'objet

Tous les champs sont toujours présents ; un champ sans valeur vaut null.

ChampTypeDescription
object string Toujours « event ».
id string Id unique (evt_…). Identique à l'en-tête webhook-id : utilisez-le pour reconnaître les messages en double.
type string Le type d'événement, par exemple customer.created. l'une des valeurs : customer.created, customer.updated, customer.converted, deal.created, deal.updated, deal.stage_changed, deal.won, deal.lost, note.created, note.updated, note.deleted
created_at string (date-time) Quand cela s'est produit (UTC).
data object Le contenu de l'événement.
data.object object L'objet tel qu'il était après la modification, sous la même forme que dans l'API REST (pour note.deleted : tel qu'il était avant la suppression).