Aller au contenu
KelkiDéveloppeurs

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 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

NomOùRequisTypeDescription
Idempotency-Keyheaderouistring

8 à 64 caractères, unique par opération. Même clé + même corps sous 24 h = même réponse.

motif ^[A-Za-z0-9_\-]{8,64}$

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

CodeDescriptionContenu
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

NomOùRequisTypeDescription
statusquerynonRequestStatus

valeurs : draft, draft_expired, awaiting_confirmation, abandoned, cancelled, transmitted, sold, not_taken, called_back

referencequerynonPartnerReference

Votre référence.

motif ^[A-Za-z0-9._:\-]{1,64}$

created_afterquerynonstring (date-time)
limitquerynoninteger

Taille de page (1 à 100).

min. 1 · max. 100 · défaut 20

starting_afterquerynonstring

Curseur opaque next_cursor de la page précédente.

max. 200 car.

Réponses

CodeDescriptionContenu
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

NomOùRequisTypeDescription
request_idpathouistring

motif ^req_[0-9A-Z]{26}$

Réponses

CodeDescriptionContenu
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

NomOùRequisTypeDescription
request_idpathouistring

motif ^req_[0-9A-Z]{26}$

Idempotency-Keyheaderouistring

8 à 64 caractères, unique par opération. Même clé + même corps sous 24 h = même réponse.

motif ^[A-Za-z0-9_\-]{8,64}$

Corps de la requête

application/merge-patch+json — RequestUpdate (obligatoire)

{
  "delay": "Dans la semaine"
}

Réponses

CodeDescriptionContenu
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

NomOùRequisTypeDescription
request_idpathouistring

motif ^req_[0-9A-Z]{26}$

Idempotency-Keyheaderouistring

8 à 64 caractères, unique par opération. Même clé + même corps sous 24 h = même réponse.

motif ^[A-Za-z0-9_\-]{8,64}$

Réponses

CodeDescriptionContenu
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. Statut awaiting_confirmation, puis transmitted après le clic, ou abandoned sans clic sous 48 h.
  • partner_attestation (portée consent.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. Statut transmitted immé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

NomOùRequisTypeDescription
request_idpathouistring

motif ^req_[0-9A-Z]{26}$

Idempotency-Keyheaderouistring

8 à 64 caractères, unique par opération. Même clé + même corps sous 24 h = même réponse.

motif ^[A-Za-z0-9_\-]{8,64}$

Corps de la requête

application/json — ConfirmationCreate (obligatoire)

{
  "method": "email",
  "consent_text_version": "v2026-10-18",
  "consent_given": true
}

Réponses

CodeDescriptionContenu
202

E-mail de confirmation envoyé (méthode email).

application/json Request
201

Attestation acceptée, demande transmise (méthode partner_attestation).

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

NomOùRequisTypeDescription
request_idpathouistring

motif ^req_[0-9A-Z]{26}$

limitquerynoninteger

Taille de page (1 à 100).

min. 1 · max. 100 · défaut 20

starting_afterquerynonstring

Curseur opaque next_cursor de la page précédente.

max. 200 car.

Réponses

CodeDescriptionContenu
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

NomOùRequisTypeDescription
request_idpathouistring

motif ^req_[0-9A-Z]{26}$

Corps de la requête

application/json — SimulateStatus (obligatoire)

{
  "status": "sold"
}

Réponses

CodeDescriptionContenu
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

ChampTypeRequisDescription
countryCountryCodenon
langLanguageCodenon
trade_idstringoui

max. 60 car.

servicestringoui

Une valeur de Trade.services.

max. 120 car.

other_needstringnon

Obligatoire avec « Autre besoin ».

min. 3 car. · max. 160 car.

delaystringoui

Un libellé de Trade.delays.

max. 60 car.

place_idstringoui

Identifiant renvoyé par GET /places.

max. 130 car.

contactContactoui
messagestringnon

Précisions de la personne. Pas de donnée de santé.

max. 2000 car.

referencePartnerReferencenon
end_user_refstringnon

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 ^[A-Za-z0-9_\-]{6,64}$

Request

Aucune coordonnée en clair, aucun professionnel, aucune provenance, aucun identifiant interne.

ChampTypeRequisDescription
idstringoui

motif ^req_[0-9A-Z]{26}$

objectstringoui

valeur : request

modestringoui

valeurs : test, live

statusRequestStatusoui
status_changed_atstring (date-time)oui
created_atstring (date-time)oui
expires_atstring | null (date-time)non

Fin du brouillon (2 h) ou de la confirmation (48 h).

referencestring | nullnon
channelstringnon

valeurs : requests, agent

countryCountryCodeoui
langLanguageCodenon
tradeobjectoui
servicestringoui
other_needstringnon
delaystringoui
placeobjectoui
contact_maskedMaskedContactnon
recapstringnon

Récapitulatif à montrer à la personne avant son accord (brouillon seulement).

consentConsentTextnon
confirmationConfirmationnon
callbackCallbacknon

Problem

Détails d'un problème (RFC 9457), avec des membres d'extension.

ChampTypeRequisDescription
typestring (uri)oui

URI stable du type de problème ; elle mène à sa documentation.

titlestringoui
statusintegeroui

min. 400 · max. 599

detailstringnon
instancestring (uri-reference)non
codestringoui

Code stable, lisible par une machine.

valeurs : invalid_json, invalid_parameter, payload_too_large, unsupported_media_type, invalid_credentials, expired_token, insufficient_scope, live_not_enabled, account_suspended, country_not_available, trade_not_available, not_found, invalid_state, idempotency_in_progress, idempotency_key_reused, validation_failed, consent_missing, consent_version_outdated, contact_limit_reached, duplicate_request, rate_limited, quota_exceeded, agent_paused, live_creation_paused, service_unavailable, internal_error

request_idstringoui
errorstableau de FieldErrornon

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

ChampTypeRequisDescription
servicestringnon

max. 120 car.

other_needstringnon

max. 160 car.

delaystringnon

max. 60 car.

place_idstringnon

max. 130 car.

contactContactnon
messagestring | nullnon

max. 2000 car.

referencePartnerReferencenon

ConfirmationCreate

Méthode de confirmation, choisie par method.

Type : EmailConfirmationCreate ou AttestationConfirmationCreate

RequestEventList

Type : ListMeta et object

SimulateStatus

ChampTypeRequisDescription
statusstringoui

valeurs : transmitted, abandoned, sold, not_taken, called_back

CountryCode

Type : string — motif ^[A-Z]{2}$ · défaut "FR"

LanguageCode

Type : string — motif ^[a-z]{2}$

Contact

ChampTypeRequisDescription
namestringoui

min. 2 car. · max. 80 car.

phonestringoui

Format E.164. Doit être un numéro valide du pays de la demande.

motif ^\+[1-9]\d{6,14}$

emailstring (email)oui

Reçoit l'e-mail de confirmation (méthode email) ou d'information (attestation).

max. 254 car.

MaskedContact

ChampTypeRequisDescription
namestringnon
phonestringnon
emailstringnon

ConsentText

ChampTypeRequisDescription
versionstringoui

motif ^v\d{4}-\d{2}-\d{2}$

langLanguageCodeoui
textstringoui

À afficher mot pour mot, à côté d'une case non cochée par défaut.

valid_fromstring (date)oui

Confirmation

ChampTypeRequisDescription
methodstringoui

valeurs : email, partner_attestation

sent_atstring | null (date-time)non
expires_atstring | null (date-time)non
confirmed_atstring | 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).

ChampTypeRequisDescription
reportedstring | nulloui

valeurs : yes, not_yet,

reported_atstring | null (date-time)oui

FieldError

ChampTypeRequisDescription
pointerstringoui

JSON Pointer (RFC 6901) du champ en cause.

detailstringoui
allowedtableau de stringnon

Valeurs acceptées, quand la liste est fermée.

ListMeta

ChampTypeRequisDescription
objectstringoui

valeur : list

has_morebooleanoui
next_cursorstring | nulloui

EmailConfirmationCreate

ChampTypeRequisDescription
methodstringoui

valeur : email

consent_text_versionstringoui

Version du texte montré ; doit être celle du brouillon.

motif ^v\d{4}-\d{2}-\d{2}$

consent_givenbooleanoui

La personne a coché la case d'accord après avoir vu le récapitulatif.

valeur : True

AttestationConfirmationCreate

ChampTypeRequisDescription
methodstringoui

valeur : partner_attestation

consent_text_versionstringoui

Version du texte montré ; doit être celle du brouillon.

motif ^v\d{4}-\d{2}-\d{2}$

consent_givenbooleanoui

valeur : True

attestationAttestationoui

Attestation

ChampTypeRequisDescription
consented_atstring (date-time)oui

Horodatage UTC du clic de la personne. Au plus 15 minutes avant l'appel.

language_shownLanguageCodeoui
recap_shownbooleanoui

valeur : True

checkbox_unticked_by_defaultbooleanoui

valeur : True

subject_authenticationstringoui

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 : account_email_verified, account_phone_verified, one_time_code

evidence_idstringoui

Identifiant de votre preuve (journal), sans donnée personnelle. Produite sur demande de Kelki.

motif ^[A-Za-z0-9._:\-]{4,64}$