Demandes
Brouillon, confirmation par la personne, suivi. Une demande confirmée suit le circuit normal (Leads Hub puis vente à un seul professionnel).
Outils réservés au mode test.
Adresse de base : https://kelki.ai/api/v1.
POST /requests— Créer un brouillon de demandeGET /requests— Lister vos demandesGET /requests/{request_id}— Lire une demande et son statutPATCH /requests/{request_id}— Modifier un brouillonDELETE /requests/{request_id}— Annuler une demande non transmisePOST /requests/{request_id}/confirmation— Lancer la confirmation par la personneGET /requests/{request_id}/events— Historique des statuts d'une demandePOST /sandbox/requests/{request_id}/simulate— Faire avancer une demande de test
POST /requests
Créer un brouillon de demande
Valide la demande avec les règles du formulaire et renvoie un brouillon (status: draft) avec le récapitulatif et le texte d'accord à montrer à la personne. Rien n'est transmis à ce stade. Le brouillon expire au bout de 2 heures ; ses coordonnées sont alors effacées.
Authentification : clé API (Authorization: Bearer kk_…) ou jeton OAuth 2.0 (portée requests.write).
Paramètres
| Nom | Où | Requis | Type | Description |
|---|---|---|---|---|
Idempotency-Key | header | oui | string | 8 à 64 caractères, unique par opération. Même clé + même corps sous 24 h = même réponse. motif |
Corps de la requête
application/json — RequestCreate (obligatoire)
{
"country": "FR",
"lang": "fr",
"trade_id": "plombier",
"service": "Recherche de fuite",
"delay": "Dès que possible",
"place_id": "fr-creteil-94000",
"contact": {
"name": "Camille Exemple",
"phone": "+33639980042",
"email": "camille.exemple@example.com"
},
"message": "Fuite sous l'évier de la cuisine, robinet d'arrêt fermé.",
"reference": "resa-2026-0042",
"end_user_ref": "u_7d9f2b1c"
}Réponses
| Code | Description | Contenu |
|---|---|---|
201 | Brouillon créé. | application/json Request |
400 | Requête mal formée (JSON invalide, paramètre inconnu, corps trop gros). | application/problem+json Problem |
401 | Identifiants absents, invalides, expirés ou révoqués. | application/problem+json Problem |
403 | Portée manquante, compte non autorisé en live, pays non ouvert, compte suspendu. | application/problem+json Problem |
409 | Transition impossible (ex. modifier une demande déjà transmise) ou requête idempotente en cours. | application/problem+json Problem |
422 | Valeur refusée par les règles du formulaire (listes fermées, lieu, coordonnées, accord, limites anti-abus). | application/problem+json Problem |
429 | Débit ou quota dépassé. | application/problem+json Problem |
503 | Service en pause ou en maintenance (ex. agent en pause, création live suspendue). | application/problem+json Problem |
Exemple de réponse
{
"id": "req_01JC00000000000000000000RQ",
"object": "request",
"mode": "test",
"status": "draft",
"status_changed_at": "2026-11-11T09:41:58Z",
"created_at": "2026-11-11T09:41:58Z",
"expires_at": "2026-11-11T11:41:58Z",
"reference": "resa-2026-0042",
"channel": "requests",
"country": "FR",
"lang": "fr",
"trade": {
"id": "plombier",
"name": "Plombier"
},
"service": "Recherche de fuite",
"delay": "Dès que possible",
"place": {
"id": "fr-creteil-94000",
"label": "Créteil (94000)"
},
"contact_masked": {
"name": "C•••",
"phone": "+33 6 •• •• •• 42",
"email": "c•••@example.com"
},
"recap": "Plombier — Recherche de fuite, dès que possible, à Créteil (94000). Rappel de C••• au +33 6 •• •• •• 42.",
"consent": {
"version": "v2026-10-18",
"lang": "fr",
"text": "J’accepte que ma demande et mes coordonnées soient transmises à un ou plusieurs professionnels du métier de mon secteur, qui pourront me rappeler à ce sujet.",
"valid_from": "2026-11-10"
}
}GET /requests
Lister vos demandes
Demandes du compte et du mode de l'identifiant utilisé, de la plus récente à la plus ancienne.
Authentification : clé API (Authorization: Bearer kk_…) ou jeton OAuth 2.0 (portée requests.read).
Paramètres
| Nom | Où | Requis | Type | Description |
|---|---|---|---|---|
status | query | non | RequestStatus | valeurs : |
reference | query | non | PartnerReference | Votre référence. motif |
created_after | query | non | string (date-time) | |
limit | query | non | integer | Taille de page (1 à 100). min. 1 · max. 100 · défaut |
starting_after | query | non | string | Curseur opaque max. 200 car. |
Réponses
| Code | Description | Contenu |
|---|---|---|
200 | Une page de demandes. | application/json RequestList |
400 | Requête mal formée (JSON invalide, paramètre inconnu, corps trop gros). | application/problem+json Problem |
401 | Identifiants absents, invalides, expirés ou révoqués. | application/problem+json Problem |
429 | Débit ou quota dépassé. | application/problem+json Problem |
Exemple de réponse
{
"object": "list",
"has_more": false,
"next_cursor": null,
"data": [
{
"id": "req_01JC00000000000000000000RQ",
"object": "request",
"mode": "live",
"status": "called_back",
"status_changed_at": "2026-11-13T18:02:11Z",
"created_at": "2026-11-11T09:41:58Z",
"reference": "resa-2026-0042",
"channel": "requests",
"country": "FR",
"lang": "fr",
"trade": {
"id": "plombier",
"name": "Plombier"
},
"service": "Recherche de fuite",
"delay": "Dès que possible",
"place": {
"id": "fr-creteil-94000",
"label": "Créteil (94000)"
},
"callback": {
"reported": "yes",
"reported_at": "2026-11-13T18:02:11Z"
}
}
]
}GET /requests/{request_id}
Lire une demande et son statut
Authentification : clé API (Authorization: Bearer kk_…) ou jeton OAuth 2.0 (portée requests.read).
Paramètres
| Nom | Où | Requis | Type | Description |
|---|---|---|---|---|
request_id | path | oui | string | motif |
Réponses
| Code | Description | Contenu |
|---|---|---|
200 | La demande. Coordonnées masquées ; jamais de professionnel, jamais de provenance. | application/json Request |
401 | Identifiants absents, invalides, expirés ou révoqués. | application/problem+json Problem |
404 | Ressource inconnue, ou appartenant à un autre compte ou à un autre mode (même réponse). | application/problem+json Problem |
429 | Débit ou quota dépassé. | application/problem+json Problem |
Exemple de réponse
{
"id": "req_01JC00000000000000000000RQ",
"object": "request",
"mode": "live",
"status": "sold",
"status_changed_at": "2026-11-11T10:15:40Z",
"created_at": "2026-11-11T09:41:58Z",
"reference": "resa-2026-0042",
"channel": "requests",
"country": "FR",
"lang": "fr",
"trade": {
"id": "plombier",
"name": "Plombier"
},
"service": "Recherche de fuite",
"delay": "Dès que possible",
"place": {
"id": "fr-creteil-94000",
"label": "Créteil (94000)"
},
"contact_masked": {
"name": "C•••",
"phone": "+33 6 •• •• •• 42",
"email": "c•••@example.com"
},
"confirmation": {
"method": "email",
"sent_at": "2026-11-11T09:42:12Z",
"confirmed_at": "2026-11-11T09:47:03Z"
},
"callback": {
"reported": null,
"reported_at": null
}
}PATCH /requests/{request_id}
Modifier un brouillon
Possible seulement au statut draft. Le récapitulatif est recalculé ; l'accord doit être redonné ensuite.
Authentification : clé API (Authorization: Bearer kk_…) ou jeton OAuth 2.0 (portée requests.write).
Paramètres
| Nom | Où | Requis | Type | Description |
|---|---|---|---|---|
request_id | path | oui | string | motif |
Idempotency-Key | header | oui | string | 8 à 64 caractères, unique par opération. Même clé + même corps sous 24 h = même réponse. motif |
Corps de la requête
application/merge-patch+json — RequestUpdate (obligatoire)
{
"delay": "Dans la semaine"
}Réponses
| Code | Description | Contenu |
|---|---|---|
200 | Brouillon modifié. | application/json Request |
401 | Identifiants absents, invalides, expirés ou révoqués. | application/problem+json Problem |
404 | Ressource inconnue, ou appartenant à un autre compte ou à un autre mode (même réponse). | application/problem+json Problem |
409 | Transition impossible (ex. modifier une demande déjà transmise) ou requête idempotente en cours. | application/problem+json Problem |
422 | Valeur refusée par les règles du formulaire (listes fermées, lieu, coordonnées, accord, limites anti-abus). | application/problem+json Problem |
Exemple de réponse
{
"id": "req_01JC00000000000000000000RQ",
"object": "request",
"mode": "test",
"status": "draft",
"status_changed_at": "2026-11-11T09:41:58Z",
"created_at": "2026-11-11T09:41:58Z",
"expires_at": "2026-11-11T11:41:58Z",
"reference": "resa-2026-0042",
"channel": "requests",
"country": "FR",
"lang": "fr",
"trade": {
"id": "plombier",
"name": "Plombier"
},
"service": "Recherche de fuite",
"delay": "Dès que possible",
"place": {
"id": "fr-creteil-94000",
"label": "Créteil (94000)"
},
"contact_masked": {
"name": "C•••",
"phone": "+33 6 •• •• •• 42",
"email": "c•••@example.com"
},
"recap": "Plombier — Recherche de fuite, dès que possible, à Créteil (94000). Rappel de C••• au +33 6 •• •• •• 42.",
"consent": {
"version": "v2026-10-18",
"lang": "fr",
"text": "J’accepte que ma demande et mes coordonnées soient transmises à un ou plusieurs professionnels du métier de mon secteur, qui pourront me rappeler à ce sujet.",
"valid_from": "2026-11-10"
}
}DELETE /requests/{request_id}
Annuler une demande non transmise
Brouillon ou demande en attente de confirmation : annulée, coordonnées effacées immédiatement. Une demande déjà transmise ne peut plus être annulée par l'API : la personne exerce ses droits auprès de Kelki (lien dans ses e-mails).
Authentification : clé API (Authorization: Bearer kk_…) ou jeton OAuth 2.0 (portée requests.write).
Paramètres
| Nom | Où | Requis | Type | Description |
|---|---|---|---|---|
request_id | path | oui | string | motif |
Idempotency-Key | header | oui | string | 8 à 64 caractères, unique par opération. Même clé + même corps sous 24 h = même réponse. motif |
Réponses
| Code | Description | Contenu |
|---|---|---|
200 | Demande annulée. | application/json Request |
401 | Identifiants absents, invalides, expirés ou révoqués. | application/problem+json Problem |
404 | Ressource inconnue, ou appartenant à un autre compte ou à un autre mode (même réponse). | application/problem+json Problem |
409 | Transition impossible (ex. modifier une demande déjà transmise) ou requête idempotente en cours. | application/problem+json Problem |
POST /requests/{request_id}/confirmation
Lancer la confirmation par la personne
Deux méthodes :
email(par défaut, tous les comptes) : Kelki envoie à la personne l'e-mail « Confirmer ma demande » (48 h, page/confirmer/<jeton>de kelki.ai). Le lien n'est jamais donné au partenaire. Statutawaiting_confirmation, puistransmittedaprès le clic, ouabandonedsans clic sous 48 h.partner_attestation(portéeconsent.attest, comptes agréés sous contrat) : le partenaire atteste avoir montré le récapitulatif et le texte d'accord, et recueilli l'accord explicite de la personne authentifiée. Statuttransmittedimmédiatement ; Kelki envoie à la personne un e-mail d'information avec un lien « Ce n'était pas moi ».
Authentification : clé API (Authorization: Bearer kk_…) ou jeton OAuth 2.0 (portée requests.write) ou jeton OAuth 2.0 (portée requests.write, consent.attest).
Paramètres
| Nom | Où | Requis | Type | Description |
|---|---|---|---|---|
request_id | path | oui | string | motif |
Idempotency-Key | header | oui | string | 8 à 64 caractères, unique par opération. Même clé + même corps sous 24 h = même réponse. motif |
Corps de la requête
application/json — ConfirmationCreate (obligatoire)
{
"method": "email",
"consent_text_version": "v2026-10-18",
"consent_given": true
}Réponses
| Code | Description | Contenu |
|---|---|---|
202 | E-mail de confirmation envoyé (méthode | application/json Request |
201 | Attestation acceptée, demande transmise (méthode | application/json Request |
401 | Identifiants absents, invalides, expirés ou révoqués. | application/problem+json Problem |
403 | Portée manquante, compte non autorisé en live, pays non ouvert, compte suspendu. | application/problem+json Problem |
404 | Ressource inconnue, ou appartenant à un autre compte ou à un autre mode (même réponse). | application/problem+json Problem |
409 | Transition impossible (ex. modifier une demande déjà transmise) ou requête idempotente en cours. | application/problem+json Problem |
422 | Valeur refusée par les règles du formulaire (listes fermées, lieu, coordonnées, accord, limites anti-abus). | application/problem+json Problem |
429 | Débit ou quota dépassé. | application/problem+json Problem |
Exemple de réponse
{
"id": "req_01JC00000000000000000000RQ",
"object": "request",
"mode": "live",
"status": "awaiting_confirmation",
"status_changed_at": "2026-11-11T09:42:12Z",
"created_at": "2026-11-11T09:41:58Z",
"expires_at": "2026-11-13T09:42:12Z",
"reference": "resa-2026-0042",
"channel": "requests",
"country": "FR",
"lang": "fr",
"trade": {
"id": "plombier",
"name": "Plombier"
},
"service": "Recherche de fuite",
"delay": "Dès que possible",
"place": {
"id": "fr-creteil-94000",
"label": "Créteil (94000)"
},
"contact_masked": {
"name": "C•••",
"phone": "+33 6 •• •• •• 42",
"email": "c•••@example.com"
},
"confirmation": {
"method": "email",
"sent_at": "2026-11-11T09:42:12Z",
"expires_at": "2026-11-13T09:42:12Z"
}
}GET /requests/{request_id}/events
Historique des statuts d'une demande
Authentification : clé API (Authorization: Bearer kk_…) ou jeton OAuth 2.0 (portée requests.read).
Paramètres
| Nom | Où | Requis | Type | Description |
|---|---|---|---|---|
request_id | path | oui | string | motif |
limit | query | non | integer | Taille de page (1 à 100). min. 1 · max. 100 · défaut |
starting_after | query | non | string | Curseur opaque max. 200 car. |
Réponses
| Code | Description | Contenu |
|---|---|---|
200 | Événements, du plus ancien au plus récent. | application/json RequestEventList |
401 | Identifiants absents, invalides, expirés ou révoqués. | application/problem+json Problem |
404 | Ressource inconnue, ou appartenant à un autre compte ou à un autre mode (même réponse). | application/problem+json Problem |
Exemple de réponse
{
"object": "list",
"has_more": false,
"next_cursor": null,
"data": [
{
"id": "evt_01JC0000000000000000000001",
"type": "request.status_changed",
"status": "awaiting_confirmation",
"occurred_at": "2026-11-11T09:42:12Z"
},
{
"id": "evt_01JC0000000000000000000002",
"type": "request.status_changed",
"status": "transmitted",
"occurred_at": "2026-11-11T09:47:03Z"
},
{
"id": "evt_01JC0000000000000000000003",
"type": "request.status_changed",
"status": "sold",
"occurred_at": "2026-11-11T10:15:40Z"
}
]
}POST /sandbox/requests/{request_id}/simulate
Faire avancer une demande de test
Mode test uniquement (identifiants kk_test_…). Déclenche les mêmes webhooks qu'en production.
Authentification : clé API (Authorization: Bearer kk_…) ou jeton OAuth 2.0 (portée requests.write).
Paramètres
| Nom | Où | Requis | Type | Description |
|---|---|---|---|---|
request_id | path | oui | string | motif |
Corps de la requête
application/json — SimulateStatus (obligatoire)
{
"status": "sold"
}Réponses
| Code | Description | Contenu |
|---|---|---|
200 | Statut appliqué. | application/json Request |
401 | Identifiants absents, invalides, expirés ou révoqués. | application/problem+json Problem |
403 | Portée manquante, compte non autorisé en live, pays non ouvert, compte suspendu. | application/problem+json Problem |
404 | Ressource inconnue, ou appartenant à un autre compte ou à un autre mode (même réponse). | application/problem+json Problem |
409 | Transition impossible (ex. modifier une demande déjà transmise) ou requête idempotente en cours. | application/problem+json Problem |
Schémas
RequestCreate
| Champ | Type | Requis | Description |
|---|---|---|---|
country | CountryCode | non | |
lang | LanguageCode | non | |
trade_id | string | oui | max. 60 car. |
service | string | oui | Une valeur de max. 120 car. |
other_need | string | non | Obligatoire avec « Autre besoin ». min. 3 car. · max. 160 car. |
delay | string | oui | Un libellé de max. 60 car. |
place_id | string | oui | Identifiant renvoyé par GET /places. max. 130 car. |
contact | Contact | oui | |
message | string | non | Précisions de la personne. Pas de donnée de santé. max. 2000 car. |
reference | PartnerReference | non | |
end_user_ref | string | non | Identifiant opaque et stable de l'utilisateur chez vous (pseudonyme, jamais un e-mail ou un numéro). Sert aux limites anti-abus par utilisateur. motif |
Request
Aucune coordonnée en clair, aucun professionnel, aucune provenance, aucun identifiant interne.
| Champ | Type | Requis | Description |
|---|---|---|---|
id | string | oui | motif |
object | string | oui | valeur : |
mode | string | oui | valeurs : |
status | RequestStatus | oui | |
status_changed_at | string (date-time) | oui | |
created_at | string (date-time) | oui | |
expires_at | string | null (date-time) | non | Fin du brouillon (2 h) ou de la confirmation (48 h). |
reference | string | null | non | |
channel | string | non | valeurs : |
country | CountryCode | oui | |
lang | LanguageCode | non | |
trade | object | oui | |
service | string | oui | |
other_need | string | non | |
delay | string | oui | |
place | object | oui | |
contact_masked | MaskedContact | non | |
recap | string | non | Récapitulatif à montrer à la personne avant son accord (brouillon seulement). |
consent | ConsentText | non | |
confirmation | Confirmation | non | |
callback | Callback | non |
Problem
Détails d'un problème (RFC 9457), avec des membres d'extension.
| Champ | Type | Requis | Description |
|---|---|---|---|
type | string (uri) | oui | URI stable du type de problème ; elle mène à sa documentation. |
title | string | oui | |
status | integer | oui | min. 400 · max. 599 |
detail | string | non | |
instance | string (uri-reference) | non | |
code | string | oui | Code stable, lisible par une machine. valeurs : |
request_id | string | oui | |
errors | tableau de FieldError | non |
RequestStatus
draft : brouillon, rien n'est transmis · draft_expired : brouillon expiré (2 h), coordonnées effacées · awaiting_confirmation : e-mail envoyé, en attente du clic (48 h) · abandoned : pas de clic sous 48 h, coordonnées effacées · cancelled : annulée par le partenaire avant transmission · transmitted : confirmée et proposée aux professionnels · sold : prise par un seul professionnel · not_taken : aucun professionnel ne l'a prise pendant la durée de l'offre · called_back : la personne a confirmé avoir été rappelée.
Type : string — valeurs : draft, draft_expired, awaiting_confirmation, abandoned, cancelled, transmitted, sold, not_taken, called_back
PartnerReference
Votre référence (ex. n° de réservation). Sans donnée personnelle. Renvoyée dans les webhooks.
Type : string — motif ^[A-Za-z0-9._:\-]{1,64}$
RequestList
Type : ListMeta et object
RequestUpdate
| Champ | Type | Requis | Description |
|---|---|---|---|
service | string | non | max. 120 car. |
other_need | string | non | max. 160 car. |
delay | string | non | max. 60 car. |
place_id | string | non | max. 130 car. |
contact | Contact | non | |
message | string | null | non | max. 2000 car. |
reference | PartnerReference | non |
ConfirmationCreate
Méthode de confirmation, choisie par method.
Type : EmailConfirmationCreate ou AttestationConfirmationCreate
RequestEventList
Type : ListMeta et object
SimulateStatus
| Champ | Type | Requis | Description |
|---|---|---|---|
status | string | oui | valeurs : |
CountryCode
Type : string — motif ^[A-Z]{2}$ · défaut "FR"
LanguageCode
Type : string — motif ^[a-z]{2}$
Contact
| Champ | Type | Requis | Description |
|---|---|---|---|
name | string | oui | min. 2 car. · max. 80 car. |
phone | string | oui | Format E.164. Doit être un numéro valide du pays de la demande. motif |
email | string (email) | oui | Reçoit l'e-mail de confirmation (méthode email) ou d'information (attestation). max. 254 car. |
MaskedContact
| Champ | Type | Requis | Description |
|---|---|---|---|
name | string | non | |
phone | string | non | |
email | string | non |
ConsentText
| Champ | Type | Requis | Description |
|---|---|---|---|
version | string | oui | motif |
lang | LanguageCode | oui | |
text | string | oui | À afficher mot pour mot, à côté d'une case non cochée par défaut. |
valid_from | string (date) | oui |
Confirmation
| Champ | Type | Requis | Description |
|---|---|---|---|
method | string | oui | valeurs : |
sent_at | string | null (date-time) | non | |
expires_at | string | null (date-time) | non | |
confirmed_at | string | null (date-time) | non |
Callback
Réponse de la personne à la question « Avez-vous été rappelé ? » (e-mail envoyé 2 jours après la vente).
| Champ | Type | Requis | Description |
|---|---|---|---|
reported | string | null | oui | valeurs : |
reported_at | string | null (date-time) | oui |
FieldError
| Champ | Type | Requis | Description |
|---|---|---|---|
pointer | string | oui | JSON Pointer (RFC 6901) du champ en cause. |
detail | string | oui | |
allowed | tableau de string | non | Valeurs acceptées, quand la liste est fermée. |
ListMeta
| Champ | Type | Requis | Description |
|---|---|---|---|
object | string | oui | valeur : |
has_more | boolean | oui | |
next_cursor | string | null | oui |
EmailConfirmationCreate
| Champ | Type | Requis | Description |
|---|---|---|---|
method | string | oui | valeur : |
consent_text_version | string | oui | Version du texte montré ; doit être celle du brouillon. motif |
consent_given | boolean | oui | La personne a coché la case d'accord après avoir vu le récapitulatif. valeur : |
AttestationConfirmationCreate
| Champ | Type | Requis | Description |
|---|---|---|---|
method | string | oui | valeur : |
consent_text_version | string | oui | Version du texte montré ; doit être celle du brouillon. motif |
consent_given | boolean | oui | valeur : |
attestation | Attestation | oui |
Attestation
| Champ | Type | Requis | Description |
|---|---|---|---|
consented_at | string (date-time) | oui | Horodatage UTC du clic de la personne. Au plus 15 minutes avant l'appel. |
language_shown | LanguageCode | oui | |
recap_shown | boolean | oui | valeur : |
checkbox_unticked_by_default | boolean | oui | valeur : |
subject_authentication | string | oui | Comment la personne est authentifiée chez vous ; l'e-mail ou le téléphone de la demande doit être celui que vous avez vérifié. valeurs : |
evidence_id | string | oui | Identifiant de votre preuve (journal), sans donnée personnelle. Produite sur demande de Kelki. motif |