Skip to content
KelkiDevelopers

Guide: form without the agent

Your screens, Kelki's lists, no AI model. The flow follows the kelki.ai “Call me back” form: the service, the timing, the place, your details, then consent.

Typical screens

  1. The service. Trade chosen by the person (after POST /trade-matches or from GET /trades), then a service from services. “Autre besoin” (other need, other_need_label) opens a free other_need field of 3 to 160 characters.
  2. The timing. A label from delays (urgent: true flags urgent timings).
  3. The place. “Town or postcode” field → GET /places?q=… → the person picks a place; keep its id. No precise address.
  4. The contact details. Name (2 to 80 characters), phone in E.164 format valid for the request's country (+33639980042), e-mail (it receives the confirmation); optional details (message, 2,000 characters at most, no health data).
  5. Summary and consent. POST /requests, then recap and the consent text word for word, unticked box, then POST /requests/{request_id}/confirmation (rules).

Closed lists

The values of service and delay must come exactly from the trade's lists, in the language of the request. A value outside the list is refused:

{
  "type": "https://kelki.ai/api/problems/validation_failed",
  "title": "Demande invalide",
  "status": 422,
  "code": "validation_failed",
  "errors": [{"pointer": "/service", "detail": "Prestation hors liste pour Plombier.",
              "allowed": ["Recherche de fuite", "Réparation de fuite", "Débouchage", "Autre besoin"]}]
}

errors[].pointer points to the field; allowed gives the accepted values: your screen can offer the correction directly. Messages follow the language of the request (French here). The schema is closed: any unknown field is refused.

The fields of POST /requests

FieldRule
trade_ididentifier of a trade open to the API
servicea value from the trade's services
other_needrequired with “Autre besoin” (3 to 160 characters)
delaya label from delays
place_ididentifier returned by GET /places
contactname, phone, email of the person to call back
messageoptional, 2,000 characters at most, no health data
referenceoptional: your reference (e.g. booking number), without personal data
end_user_refoptional: stable pseudonym of the user on your side (never an e-mail or a number)
country, langoptional: FR and the country's main language by default

Correcting a draft

PATCH /requests/{request_id} (application/merge-patch+json) in draft status: the summary is recomputed, consent must be given again afterwards. DELETE cancels and erases the contact details.