KelkunDéveloppeurs

Suivre ses leads

Savoir ce que sont devenus les leads que vous nous avez envoyés : gardés, rendus, et où en est la demande.

Relisez à tout moment les leads envoyés avec votre clé, et ce qu'ils sont devenus chez nous. La même clé que pour l'envoi suffit.

curl "https://api.kelkun.app/lead-providers/leads?updated_since=2026-11-01T00:00:00Z" \
  -H "x-api-key: <votre clé>"

Notre réponse

Un 200, avec une page de vos leads, du plus ancien changement au plus récent :

{
  "data": [
    {
      "reference": "V0YDH",
      "lead_id": "LV-90001",
      "status": "kept",
      "stage": "open",
      "received_at": "2026-11-02T08:00:00.000Z",
      "kept_at": "2026-11-02T08:12:00.000Z",
      "returned_at": null,
      "return_reason": null,
      "updated_at": "2026-11-02T08:12:00.000Z"
    }
  ],
  "has_more": false
}
statusCe que le lead est devenu
receivedReçu, pas encore pris en main
in_progressLe particulier est en cours de rappel
keptGardé : le particulier est devenu une demande chez nous
returnedNon exploité, rendu (returned_at en donne la date)

Pour un lead gardé, stage dit où en est la demande : open tant qu'elle est en cours, closed une fois terminée, canceled si le particulier l'a annulée.

Pour un lead rendu, return_reason dit pourquoi :

return_reasonPourquoi le lead a été rendu
unreachableInjoignable après plusieurs essais
wrong_numberFaux numéro, ou numéro non attribué
not_requestedLa personne dit n'avoir rien demandé
fake_requestDemande fictive
project_abandonedProjet abandonné ou reporté
found_elsewhereA trouvé un artisan ailleurs
duplicateDoublon d'une demande déjà reçue
contact_refusedNe souhaite plus être contacté
expiredDélai écoulé sans suite
otherAutre motif

return_reason vaut null tant que le lead n'est pas rendu. D'autres valeurs pourront s'ajouter : traitez une valeur inconnue comme other. Pour obtenir le motif des leads rendus avant l'arrivée de ce champ, relisez-les une fois sans updated_since.

Synchroniser

Gardez la plus grande updated_at reçue et repassez-la dans updated_since à l'appel suivant : vous ne recevez que ce qui a changé. Un lead déjà reçu peut revenir ; gardez la dernière version de chaque reference.

ParamètreRôle
updated_sinceSeulement les leads changés depuis cette date (ISO 8601, UTC)
lead_idUn lead, par votre identifiant
limitLeads par page, 100 par défaut, 200 au plus
offsetLeads à sauter : tant que has_more vaut true, relancez avec offset augmenté de limit

Pour un seul lead, désigné par notre référence :

curl "https://api.kelkun.app/lead-providers/leads/V0YDH" \
  -H "x-api-key: <votre clé>"

Vous ne voyez que les leads envoyés avec votre clé.

Les refus

HTTPerrorCas
400INVALID_PAYLOADParamètre mal formé ou inconnu
404LEAD_NOT_FOUNDAucun lead de cette référence n'a été envoyé avec votre clé

Référence

GET
/lead-providers/leads
x-api-key<token>

La clé d'API que Kelkun vous a transmise.

Dans: header

Paramètres de requête

updated_since?string

Ne renvoie que les leads dont le suivi a changé depuis cette date (ISO 8601, UTC). Un lead déjà reçu peut revenir : gardez la dernière version de chaque reference.

Formatdate-time
lead_id?string

Votre identifiant de lead, tel que vous nous l'avez envoyé.

Longueurlength <= 128
limit?number

Nombre de leads par page.

Plage1 <= value <= 200
Par défaut100
offset?number

Nombre de leads à sauter, pour lire la page suivante.

Plage0 <= value
Par défaut0

Corps de la réponse

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/lead-providers/leads"
{  "data": [    {      "reference": "V0YDH",      "lead_id": "LV-90001",      "status": "kept",      "stage": "open",      "received_at": "2026-11-02T08:00:00.000Z",      "kept_at": "2026-11-02T08:12:00.000Z",      "returned_at": null,      "return_reason": null,      "updated_at": "2026-11-02T08:12:00.000Z"    }  ],  "has_more": false}
GET
/lead-providers/leads/{reference}
x-api-key<token>

La clé d'API que Kelkun vous a transmise.

Dans: header

Paramètres de chemin

reference*string

La référence du lead, rendue à son envoi.

Corps de la réponse

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/lead-providers/leads/V0YDH"
{  "reference": "V0YDH",  "lead_id": "LV-90001",  "status": "kept",  "stage": "open",  "received_at": "2026-11-02T08:00:00.000Z",  "kept_at": "2026-11-02T08:12:00.000Z",  "returned_at": null,  "return_reason": null,  "updated_at": "2026-11-02T08:12:00.000Z"}

Sur cette page