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 requestGET /requests— List your requestsGET /requests/{request_id}— Read a request and its statusPATCH /requests/{request_id}— Update a draftDELETE /requests/{request_id}— Cancel a request that has not been sentPOST /requests/{request_id}/confirmation— Start the confirmation by the personGET /requests/{request_id}/events— Status history of a requestPOST /sandbox/requests/{request_id}/simulate— Move a test request forward
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
| Name | In | Required | Type | Description |
|---|---|---|---|---|
Idempotency-Key | header | yes | string | 8 to 64 characters, unique per operation. Same key + same body within 24 h = same response. pattern |
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
| Code | Description | Content |
|---|---|---|
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
| Name | In | Required | Type | Description |
|---|---|---|---|---|
status | query | no | RequestStatus | values: |
reference | query | no | PartnerReference | Your reference. pattern |
created_after | query | no | string (date-time) | |
limit | query | no | integer | Page size (1 to 100). min. 1 · max. 100 · default |
starting_after | query | no | string | Opaque max. 200 chars |
Responses
| Code | Description | Content |
|---|---|---|
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
| Name | In | Required | Type | Description |
|---|---|---|---|---|
request_id | path | yes | string | pattern |
Responses
| Code | Description | Content |
|---|---|---|
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
| Name | In | Required | Type | Description |
|---|---|---|---|---|
request_id | path | yes | string | pattern |
Idempotency-Key | header | yes | string | 8 to 64 characters, unique per operation. Same key + same body within 24 h = same response. pattern |
Request body
application/merge-patch+json — RequestUpdate (required)
{
"delay": "Dans la semaine"
}Responses
| Code | Description | Content |
|---|---|---|
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
| Name | In | Required | Type | Description |
|---|---|---|---|---|
request_id | path | yes | string | pattern |
Idempotency-Key | header | yes | string | 8 to 64 characters, unique per operation. Same key + same body within 24 h = same response. pattern |
Responses
| Code | Description | Content |
|---|---|---|
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. Statusawaiting_confirmation, thentransmittedafter the click, orabandonedwithout a click within 48 h.partner_attestation(scopeconsent.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. Statustransmittedimmediately; 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
| Name | In | Required | Type | Description |
|---|---|---|---|---|
request_id | path | yes | string | pattern |
Idempotency-Key | header | yes | string | 8 to 64 characters, unique per operation. Same key + same body within 24 h = same response. pattern |
Request body
application/json — ConfirmationCreate (required)
{
"method": "email",
"consent_text_version": "v2026-10-18",
"consent_given": true
}Responses
| Code | Description | Content |
|---|---|---|
202 | Confirmation e-mail sent ( | application/json Request |
201 | Attestation accepted, request transmitted ( | 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
| Name | In | Required | Type | Description |
|---|---|---|---|---|
request_id | path | yes | string | pattern |
limit | query | no | integer | Page size (1 to 100). min. 1 · max. 100 · default |
starting_after | query | no | string | Opaque max. 200 chars |
Responses
| Code | Description | Content |
|---|---|---|
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
| Name | In | Required | Type | Description |
|---|---|---|---|---|
request_id | path | yes | string | pattern |
Request body
application/json — SimulateStatus (required)
{
"status": "sold"
}Responses
| Code | Description | Content |
|---|---|---|
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
| Field | Type | Required | Description |
|---|---|---|---|
country | CountryCode | no | |
lang | LanguageCode | no | |
trade_id | string | yes | max. 60 chars |
service | string | yes | A value of max. 120 chars |
other_need | string | no | Required with “Autre besoin” (other need). min. 3 chars · max. 160 chars |
delay | string | yes | A label of max. 60 chars |
place_id | string | yes | Identifier returned by GET /places. max. 130 chars |
contact | Contact | yes | |
message | string | no | Additional details from the person. No health data. max. 2000 chars |
reference | PartnerReference | no | |
end_user_ref | string | no | 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 |
Request
No contact details in clear, no professional, no origin, no internal identifier.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | pattern |
object | string | yes | value: |
mode | string | yes | values: |
status | RequestStatus | yes | |
status_changed_at | string (date-time) | yes | |
created_at | string (date-time) | yes | |
expires_at | string | null (date-time) | no | End of the draft (2 h) or of the confirmation (48 h). |
reference | string | null | no | |
channel | string | no | values: |
country | CountryCode | yes | |
lang | LanguageCode | no | |
trade | object | yes | |
service | string | yes | |
other_need | string | no | |
delay | string | yes | |
place | object | yes | |
contact_masked | MaskedContact | no | |
recap | string | no | Summary to show to the person before their consent (draft only). |
consent | ConsentText | no | |
confirmation | Confirmation | no | |
callback | Callback | no |
Problem
Problem details (RFC 9457), with extension members.
| Field | Type | Required | Description |
|---|---|---|---|
type | string (uri) | yes | Stable URI of the problem type; it leads to its documentation. |
title | string | yes | |
status | integer | yes | min. 400 · max. 599 |
detail | string | no | |
instance | string (uri-reference) | no | |
code | string | yes | Stable, machine-readable code. values: |
request_id | string | yes | |
errors | array of FieldError | no |
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
| Field | Type | Required | Description |
|---|---|---|---|
service | string | no | max. 120 chars |
other_need | string | no | max. 160 chars |
delay | string | no | max. 60 chars |
place_id | string | no | max. 130 chars |
contact | Contact | no | |
message | string | null | no | max. 2000 chars |
reference | PartnerReference | no |
ConfirmationCreate
Confirmation method, chosen by method.
Type: EmailConfirmationCreate or AttestationConfirmationCreate
RequestEventList
Type: ListMeta and object
SimulateStatus
| Field | Type | Required | Description |
|---|---|---|---|
status | string | yes | values: |
CountryCode
Type: string — pattern ^[A-Z]{2}$ · default "FR"
LanguageCode
Type: string — pattern ^[a-z]{2}$
Contact
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | min. 2 chars · max. 80 chars |
phone | string | yes | E.164 format. Must be a valid number of the request's country. pattern |
email | string (email) | yes | Receives the confirmation e-mail (email method) or the information e-mail (attestation). max. 254 chars |
MaskedContact
| Field | Type | Required | Description |
|---|---|---|---|
name | string | no | |
phone | string | no | |
email | string | no |
ConsentText
| Field | Type | Required | Description |
|---|---|---|---|
version | string | yes | pattern |
lang | LanguageCode | yes | |
text | string | yes | To display word for word, next to a checkbox left unticked by default. |
valid_from | string (date) | yes |
Confirmation
| Field | Type | Required | Description |
|---|---|---|---|
method | string | yes | values: |
sent_at | string | null (date-time) | no | |
expires_at | string | null (date-time) | no | |
confirmed_at | string | 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).
| Field | Type | Required | Description |
|---|---|---|---|
reported | string | null | yes | values: |
reported_at | string | null (date-time) | yes |
FieldError
| Field | Type | Required | Description |
|---|---|---|---|
pointer | string | yes | JSON Pointer (RFC 6901) of the field at fault. |
detail | string | yes | |
allowed | array of string | no | Accepted values, when the list is closed. |
ListMeta
| Field | Type | Required | Description |
|---|---|---|---|
object | string | yes | value: |
has_more | boolean | yes | |
next_cursor | string | null | yes |
EmailConfirmationCreate
| Field | Type | Required | Description |
|---|---|---|---|
method | string | yes | value: |
consent_text_version | string | yes | Version of the text shown; must be the draft's version. pattern |
consent_given | boolean | yes | The person ticked the consent box after seeing the summary. value: |
AttestationConfirmationCreate
| Field | Type | Required | Description |
|---|---|---|---|
method | string | yes | value: |
consent_text_version | string | yes | Version of the text shown; must be the draft's version. pattern |
consent_given | boolean | yes | value: |
attestation | Attestation | yes |
Attestation
| Field | Type | Required | Description |
|---|---|---|---|
consented_at | string (date-time) | yes | UTC timestamp of the person's click. At most 15 minutes before the call. |
language_shown | LanguageCode | yes | |
recap_shown | boolean | yes | value: |
checkbox_unticked_by_default | boolean | yes | value: |
subject_authentication | string | yes | How the person is authenticated on your side; the e-mail or phone of the request must be the one you verified. values: |
evidence_id | string | yes | Identifier of your proof (log), without personal data. Produced at Kelki's request. pattern |