Skip to content
KelkiDevelopers

Requests

Draft, confirmation by the person, tracking. A confirmed request follows the normal flow (Leads Hub, then sale to a single professional).

Tools available in test mode only.

Base URL: https://kelki.ai/api/v1.

POST /requests

Create a draft request

Validates the request with the form's rules and returns a draft (status: draft) with the summary and the consent text to show to the person. Nothing is sent at this stage. The draft expires after 2 hours; its contact details are then erased.

Authentication: API key (Authorization: Bearer kk_…) or OAuth 2.0 token (scope requests.write).

Parameters

NameInRequiredTypeDescription
Idempotency-Keyheaderyesstring

8 to 64 characters, unique per operation. Same key + same body within 24 h = same response.

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

Request body

application/json — RequestCreate (required)

{
  "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"
}

Responses

CodeDescriptionContent
201

Draft created.

application/json Request
400

Malformed request (invalid JSON, unknown parameter, body too large).

application/problem+json Problem
401

Missing, invalid, expired or revoked credentials.

application/problem+json Problem
403

Missing scope, account not enabled for live, country not open, account suspended.

application/problem+json Problem
409

Impossible transition (e.g. updating a request already transmitted) or idempotent request in progress.

application/problem+json Problem
422

Value refused by the form's rules (closed lists, place, contact details, consent, anti-abuse limits).

application/problem+json Problem
429

Rate or quota exceeded.

application/problem+json Problem
503

Service paused or under maintenance (e.g. agent paused, live creation suspended).

application/problem+json Problem

Response example

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

List your requests

Requests of the account and of the mode of the credential used, most recent first.

Authentication: API key (Authorization: Bearer kk_…) or OAuth 2.0 token (scope requests.read).

Parameters

NameInRequiredTypeDescription
statusquerynoRequestStatus

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

referencequerynoPartnerReference

Your reference.

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

created_afterquerynostring (date-time)
limitquerynointeger

Page size (1 to 100).

min. 1 · max. 100 · default 20

starting_afterquerynostring

Opaque next_cursor cursor from the previous page.

max. 200 chars

Responses

CodeDescriptionContent
200

One page of requests.

application/json RequestList
400

Malformed request (invalid JSON, unknown parameter, body too large).

application/problem+json Problem
401

Missing, invalid, expired or revoked credentials.

application/problem+json Problem
429

Rate or quota exceeded.

application/problem+json Problem

Response example

{
  "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}

Read a request and its status

Authentication: API key (Authorization: Bearer kk_…) or OAuth 2.0 token (scope requests.read).

Parameters

NameInRequiredTypeDescription
request_idpathyesstring

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

Responses

CodeDescriptionContent
200

The request. Contact details masked; never a professional, never the origin.

application/json Request
401

Missing, invalid, expired or revoked credentials.

application/problem+json Problem
404

Unknown resource, or one belonging to another account or another mode (same response).

application/problem+json Problem
429

Rate or quota exceeded.

application/problem+json Problem

Response example

{
  "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}

Update a draft

Only possible in draft status. The summary is recomputed; consent must then be given again.

Authentication: API key (Authorization: Bearer kk_…) or OAuth 2.0 token (scope requests.write).

Parameters

NameInRequiredTypeDescription
request_idpathyesstring

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

Idempotency-Keyheaderyesstring

8 to 64 characters, unique per operation. Same key + same body within 24 h = same response.

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

Request body

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

{
  "delay": "Dans la semaine"
}

Responses

CodeDescriptionContent
200

Draft updated.

application/json Request
401

Missing, invalid, expired or revoked credentials.

application/problem+json Problem
404

Unknown resource, or one belonging to another account or another mode (same response).

application/problem+json Problem
409

Impossible transition (e.g. updating a request already transmitted) or idempotent request in progress.

application/problem+json Problem
422

Value refused by the form's rules (closed lists, place, contact details, consent, anti-abuse limits).

application/problem+json Problem

Response example

{
  "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}

Cancel a request that has not been sent

Draft or request awaiting confirmation: cancelled, contact details erased immediately. A request already transmitted can no longer be cancelled through the API: the person exercises their rights with Kelki (link in their e-mails).

Authentication: API key (Authorization: Bearer kk_…) or OAuth 2.0 token (scope requests.write).

Parameters

NameInRequiredTypeDescription
request_idpathyesstring

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

Idempotency-Keyheaderyesstring

8 to 64 characters, unique per operation. Same key + same body within 24 h = same response.

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

Responses

CodeDescriptionContent
200

Request cancelled.

application/json Request
401

Missing, invalid, expired or revoked credentials.

application/problem+json Problem
404

Unknown resource, or one belonging to another account or another mode (same response).

application/problem+json Problem
409

Impossible transition (e.g. updating a request already transmitted) or idempotent request in progress.

application/problem+json Problem

POST /requests/{request_id}/confirmation

Start the confirmation by the person

Two methods:

  • email (default, all accounts): Kelki sends the person the “Confirmer ma demande” (confirm my request) e-mail (48 h, page /confirmer/<token> on kelki.ai). The link is never given to the partner. Status awaiting_confirmation, then transmitted after the click, or abandoned without a click within 48 h.
  • partner_attestation (scope consent.attest, approved accounts under contract): the partner attests that it showed the summary and the consent text, and obtained the explicit consent of the authenticated person. Status transmitted immediately; Kelki sends the person an information e-mail with a “This wasn't me” link.

Authentication: API key (Authorization: Bearer kk_…) or OAuth 2.0 token (scope requests.write) or OAuth 2.0 token (scope requests.write, consent.attest).

Parameters

NameInRequiredTypeDescription
request_idpathyesstring

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

Idempotency-Keyheaderyesstring

8 to 64 characters, unique per operation. Same key + same body within 24 h = same response.

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

Request body

application/json — ConfirmationCreate (required)

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

Responses

CodeDescriptionContent
202

Confirmation e-mail sent (email method).

application/json Request
201

Attestation accepted, request transmitted (partner_attestation method).

application/json Request
401

Missing, invalid, expired or revoked credentials.

application/problem+json Problem
403

Missing scope, account not enabled for live, country not open, account suspended.

application/problem+json Problem
404

Unknown resource, or one belonging to another account or another mode (same response).

application/problem+json Problem
409

Impossible transition (e.g. updating a request already transmitted) or idempotent request in progress.

application/problem+json Problem
422

Value refused by the form's rules (closed lists, place, contact details, consent, anti-abuse limits).

application/problem+json Problem
429

Rate or quota exceeded.

application/problem+json Problem

Response example

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

Status history of a request

Authentication: API key (Authorization: Bearer kk_…) or OAuth 2.0 token (scope requests.read).

Parameters

NameInRequiredTypeDescription
request_idpathyesstring

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

limitquerynointeger

Page size (1 to 100).

min. 1 · max. 100 · default 20

starting_afterquerynostring

Opaque next_cursor cursor from the previous page.

max. 200 chars

Responses

CodeDescriptionContent
200

Events, oldest first.

application/json RequestEventList
401

Missing, invalid, expired or revoked credentials.

application/problem+json Problem
404

Unknown resource, or one belonging to another account or another mode (same response).

application/problem+json Problem

Response example

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

Move a test request forward

Test mode only (kk_test_… credentials). Triggers the same webhooks as in production.

Authentication: API key (Authorization: Bearer kk_…) or OAuth 2.0 token (scope requests.write).

Parameters

NameInRequiredTypeDescription
request_idpathyesstring

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

Request body

application/json — SimulateStatus (required)

{
  "status": "sold"
}

Responses

CodeDescriptionContent
200

Status applied.

application/json Request
401

Missing, invalid, expired or revoked credentials.

application/problem+json Problem
403

Missing scope, account not enabled for live, country not open, account suspended.

application/problem+json Problem
404

Unknown resource, or one belonging to another account or another mode (same response).

application/problem+json Problem
409

Impossible transition (e.g. updating a request already transmitted) or idempotent request in progress.

application/problem+json Problem

Schemas

RequestCreate

FieldTypeRequiredDescription
countryCountryCodeno
langLanguageCodeno
trade_idstringyes

max. 60 chars

servicestringyes

A value of Trade.services.

max. 120 chars

other_needstringno

Required with “Autre besoin” (other need).

min. 3 chars · max. 160 chars

delaystringyes

A label of Trade.delays.

max. 60 chars

place_idstringyes

Identifier returned by GET /places.

max. 130 chars

contactContactyes
messagestringno

Additional details from the person. No health data.

max. 2000 chars

referencePartnerReferenceno
end_user_refstringno

Opaque, stable identifier of the user on your side (pseudonym, never an e-mail or a number). Used for per-user anti-abuse limits.

pattern ^[A-Za-z0-9_\-]{6,64}$

Request

No contact details in clear, no professional, no origin, no internal identifier.

FieldTypeRequiredDescription
idstringyes

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

objectstringyes

value: request

modestringyes

values: test, live

statusRequestStatusyes
status_changed_atstring (date-time)yes
created_atstring (date-time)yes
expires_atstring | null (date-time)no

End of the draft (2 h) or of the confirmation (48 h).

referencestring | nullno
channelstringno

values: requests, agent

countryCountryCodeyes
langLanguageCodeno
tradeobjectyes
servicestringyes
other_needstringno
delaystringyes
placeobjectyes
contact_maskedMaskedContactno
recapstringno

Summary to show to the person before their consent (draft only).

consentConsentTextno
confirmationConfirmationno
callbackCallbackno

Problem

Problem details (RFC 9457), with extension members.

FieldTypeRequiredDescription
typestring (uri)yes

Stable URI of the problem type; it leads to its documentation.

titlestringyes
statusintegeryes

min. 400 · max. 599

detailstringno
instancestring (uri-reference)no
codestringyes

Stable, machine-readable code.

values: 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_idstringyes
errorsarray of FieldErrorno

RequestStatus

draft: draft, nothing is sent · draft_expired: draft expired (2 h), contact details erased · awaiting_confirmation: e-mail sent, waiting for the click (48 h) · abandoned: no click within 48 h, contact details erased · cancelled: cancelled by the partner before transmission · transmitted: confirmed and offered to professionals · sold: taken by a single professional · not_taken: no professional took it during the offer period · called_back: the person confirmed they were called back.

Type: string — values: draft, draft_expired, awaiting_confirmation, abandoned, cancelled, transmitted, sold, not_taken, called_back

PartnerReference

Your reference (e.g. booking number). No personal data. Returned in webhooks.

Type: string — pattern ^[A-Za-z0-9._:\-]{1,64}$

RequestList

Type: ListMeta and object

RequestUpdate

FieldTypeRequiredDescription
servicestringno

max. 120 chars

other_needstringno

max. 160 chars

delaystringno

max. 60 chars

place_idstringno

max. 130 chars

contactContactno
messagestring | nullno

max. 2000 chars

referencePartnerReferenceno

ConfirmationCreate

Confirmation method, chosen by method.

Type: EmailConfirmationCreate or AttestationConfirmationCreate

RequestEventList

Type: ListMeta and object

SimulateStatus

FieldTypeRequiredDescription
statusstringyes

values: transmitted, abandoned, sold, not_taken, called_back

CountryCode

Type: string — pattern ^[A-Z]{2}$ · default "FR"

LanguageCode

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

Contact

FieldTypeRequiredDescription
namestringyes

min. 2 chars · max. 80 chars

phonestringyes

E.164 format. Must be a valid number of the request's country.

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

emailstring (email)yes

Receives the confirmation e-mail (email method) or the information e-mail (attestation).

max. 254 chars

MaskedContact

FieldTypeRequiredDescription
namestringno
phonestringno
emailstringno

ConsentText

FieldTypeRequiredDescription
versionstringyes

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

langLanguageCodeyes
textstringyes

To display word for word, next to a checkbox left unticked by default.

valid_fromstring (date)yes

Confirmation

FieldTypeRequiredDescription
methodstringyes

values: email, partner_attestation

sent_atstring | null (date-time)no
expires_atstring | null (date-time)no
confirmed_atstring | null (date-time)no

Callback

The person's answer to the question “Have you been called back?” (e-mail sent 2 days after the sale).

FieldTypeRequiredDescription
reportedstring | nullyes

values: yes, not_yet,

reported_atstring | null (date-time)yes

FieldError

FieldTypeRequiredDescription
pointerstringyes

JSON Pointer (RFC 6901) of the field at fault.

detailstringyes
allowedarray of stringno

Accepted values, when the list is closed.

ListMeta

FieldTypeRequiredDescription
objectstringyes

value: list

has_morebooleanyes
next_cursorstring | nullyes

EmailConfirmationCreate

FieldTypeRequiredDescription
methodstringyes

value: email

consent_text_versionstringyes

Version of the text shown; must be the draft's version.

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

consent_givenbooleanyes

The person ticked the consent box after seeing the summary.

value: True

AttestationConfirmationCreate

FieldTypeRequiredDescription
methodstringyes

value: partner_attestation

consent_text_versionstringyes

Version of the text shown; must be the draft's version.

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

consent_givenbooleanyes

value: True

attestationAttestationyes

Attestation

FieldTypeRequiredDescription
consented_atstring (date-time)yes

UTC timestamp of the person's click. At most 15 minutes before the call.

language_shownLanguageCodeyes
recap_shownbooleanyes

value: True

checkbox_unticked_by_defaultbooleanyes

value: True

subject_authenticationstringyes

How the person is authenticated on your side; the e-mail or phone of the request must be the one you verified.

values: account_email_verified, account_phone_verified, one_time_code

evidence_idstringyes

Identifier of your proof (log), without personal data. Produced at Kelki's request.

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