Skip to content
KelkiDevelopers

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)
StatusMeaning
draftDraft: nothing is sent. Can be updated (PATCH) or cancelled (DELETE).
draft_expiredDraft left without follow-up for 2 hours; contact details erased.
awaiting_confirmationE-mail sent to the person, waiting for their click (48 hours).
abandonedNo click within 48 hours; contact details erased.
cancelledCancelled by you before transmission.
transmittedConfirmed by the person and offered to the professionals of the trade in their area.
soldTaken by a single professional, who calls the person back.
not_takenNo professional took it during the offer period.
called_backThe 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

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