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.
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,FRby default.lang: ISO 639-1 code, by default the main language of the country;Accept-Languageis 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.
Conventions
- UTF-8 JSON;
Content-Type: application/jsonwhen writing,application/merge-patch+jsonforPATCH(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.