# Concepts What to know before writing the first line: a request is born as a draft, is sent only with the person's confirmed consent, and is taken by a single professional. ## Request lifecycle ``` POST /requests ──► draft ──(2 h without follow-up)──► draft_expired (contact details erased) │ PATCH (corrections); DELETE ──► cancelled │ └─ POST …/confirmation {method: email} ──► awaiting_confirmation ├─ click + button on the confirmation page ──► transmitted ├─ 48 h without a click ──► abandoned (contact details erased) └─ DELETE ──► cancelled transmitted ──► sold (taken by a single professional) ──► called_back (the person says they were called back) └──► not_taken (no professional during the offer period) ``` | Status | Meaning | | `draft` | Draft: nothing is sent. Can be updated (`PATCH`) or cancelled (`DELETE`). | | `draft_expired` | Draft left without follow-up for 2 hours; contact details erased. | | `awaiting_confirmation` | E-mail sent to the person, waiting for their click (48 hours). | | `abandoned` | No click within 48 hours; contact details erased. | | `cancelled` | Cancelled by you before transmission. | | `transmitted` | Confirmed by the person and offered to the professionals of the trade in their area. | | `sold` | Taken by a single professional, who calls the person back. | | `not_taken` | No professional took it during the offer period. | | `called_back` | The person answered “yes” to the “Have you been called back?” e-mail, sent 2 days after the sale. Without an answer, the request stays `sold`. | ## Draft and consent Creation (`POST /requests`) validates the request with the form's rules and sends nothing. Sending goes through a separate step, the confirmation, which requires the version of the consent text shown to the person (`consent_text_version`) and their ticked box (`consent_given: true`). Then the person confirms by e-mail themselves. Details: [consent of the person](https://kelki.ai/developers/en/consent/). ## A single professional A transmitted request follows Kelki's normal flow: it is offered to the professionals of the trade in the area, and only one takes it. You never receive that professional's identity or contact details. ## Local and national trades Each trade has a `scope`: `local`, dispatched by distance circles around the place; `national`, dispatched by reviews, without distance. The place is required in both cases: the professional needs to know where the person is. Trades open to the API exclude health, trades still under review by Kelki and exclusions specific to your account. Re-read the catalog (`GET /trades`) rather than hard-coding it. ## Countries and languages - `country`: ISO 3166-1 alpha-2 code in upper case, `FR` by default. - `lang`: ISO 639-1 code, by default the main language of the country; `Accept-Language` is read as a fallback. - Names of trades, services, timings and texts are in the requested language; identifiers (`plombier`, `fr-creteil-94000`) never change. ## Test and production The mode depends on the credential, never on the address: `kk_test_…` for the sandbox, `kk_live_…` for production. Every response carries the `Kelki-Mode` header. A request of one mode is invisible from the other (`404`). See [sandbox](https://kelki.ai/developers/en/sandbox/). ## Conventions - UTF-8 JSON; `Content-Type: application/json` when writing, `application/merge-patch+json` for `PATCH` (RFC 7396); bodies of 16 KB at most. - ISO 8601 dates in UTC (`2026-11-11T09:41:58Z`). - Opaque, prefixed identifiers: `req_` (request), `evt_` (event), `we_` (webhook), `conv_` (conversation), `acc_` (account). - No personal data in the address: the free need goes in a `POST`, the key is never a parameter. ## About this page - URL : https://kelki.ai/developers/en/concepts/ - Language : en - fr : https://kelki.ai/developers/fr/concepts/ - en : https://kelki.ai/developers/en/concepts/ - x-default : https://kelki.ai/developers/ - Portal : https://kelki.ai/developers/llms.txt