# 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 - GET /requests — List your requests - GET /requests/{request_id} — Read a request and its status - PATCH /requests/{request_id} — Update a draft - DELETE /requests/{request_id} — Cancel a request that has not been sent - POST /requests/{request_id}/confirmation — Start the confirmation by the person - GET /requests/{request_id}/events — Status history of a request - POST /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 `^[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 | 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: `draft`, `draft_expired`, `awaiting_confirmation`, `abandoned`, `cancelled`, `transmitted`, `sold`, `not_taken`, `called_back` | | `reference` | query | no | PartnerReference | Your reference. pattern `^[A-Za-z0-9._:\-]{1,64}$` | | `created_after` | query | no | string (date-time) | | | `limit` | query | no | integer | Page size (1 to 100). min. 1 · max. 100 · default `20` | | `starting_after` | query | no | string | Opaque `next_cursor` cursor from the previous page. 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 `^req_[0-9A-Z]{26}$` | ### 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 `^req_[0-9A-Z]{26}$` | | `Idempotency-Key` | header | yes | string | 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 | 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 `^req_[0-9A-Z]{26}$` | | `Idempotency-Key` | header | yes | string | 8 to 64 characters, unique per operation. Same key + same body within 24 h = same response. pattern `^[A-Za-z0-9_\-]{8,64}$` | ### 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/` 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 | Name | In | Required | Type | Description | | `request_id` | path | yes | string | pattern `^req_[0-9A-Z]{26}$` | | `Idempotency-Key` | header | yes | string | 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 | Code | Description | Content | | `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 | Name | In | Required | Type | Description | | `request_id` | path | yes | string | pattern `^req_[0-9A-Z]{26}$` | | `limit` | query | no | integer | Page size (1 to 100). min. 1 · max. 100 · default `20` | | `starting_after` | query | no | string | Opaque `next_cursor` cursor from the previous page. 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 `^req_[0-9A-Z]{26}$` | ### 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 `Trade.services`. 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 `Trade.delays`. 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 `^[A-Za-z0-9_\-]{6,64}$` | ### `Request` No contact details in clear, no professional, no origin, no internal identifier. | Field | Type | Required | Description | | `id` | string | yes | pattern `^req_[0-9A-Z]{26}$` | | `object` | string | yes | value: `request` | | `mode` | string | yes | values: `test`, `live` | | `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: `requests`, `agent` | | `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: `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_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: `transmitted`, `abandoned`, `sold`, `not_taken`, `called_back` | ### `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 `^\+[1-9]\d{6,14}$` | | `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 `^v\d{4}-\d{2}-\d{2}$` | | `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: `email`, `partner_attestation` | | `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: `yes`, `not_yet`, `` | | `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: `list` | | `has_more` | boolean | yes | | | `next_cursor` | string | null | yes | | ### `EmailConfirmationCreate` | Field | Type | Required | Description | | `method` | string | yes | value: `email` | | `consent_text_version` | string | yes | Version of the text shown; must be the draft's version. pattern `^v\d{4}-\d{2}-\d{2}$` | | `consent_given` | boolean | yes | The person ticked the consent box after seeing the summary. value: `True` | ### `AttestationConfirmationCreate` | Field | Type | Required | Description | | `method` | string | yes | value: `partner_attestation` | | `consent_text_version` | string | yes | Version of the text shown; must be the draft's version. pattern `^v\d{4}-\d{2}-\d{2}$` | | `consent_given` | boolean | yes | value: `True` | | `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: `True` | | `checkbox_unticked_by_default` | boolean | yes | value: `True` | | `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: `account_email_verified`, `account_phone_verified`, `one_time_code` | | `evidence_id` | string | yes | Identifier of your proof (log), without personal data. Produced at Kelki's request. pattern `^[A-Za-z0-9._:\-]{4,64}$` | ## About this page - URL : https://kelki.ai/developers/en/reference/requests/ - Language : en - fr : https://kelki.ai/developers/fr/reference/requests/ - en : https://kelki.ai/developers/en/reference/requests/ - x-default : https://kelki.ai/developers/ - Portal : https://kelki.ai/developers/llms.txt