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
- The service. Trade chosen by the person (after
POST /trade-matchesor fromGET /trades), then a service fromservices. “Autre besoin” (other need,other_need_label) opens a freeother_needfield of 3 to 160 characters. - The timing. A label from
delays(urgent: trueflags urgent timings). - The place. “Town or postcode” field →
GET /places?q=…→ the person picks a place; keep itsid. No precise address. - 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). - Summary and consent.
POST /requests, thenrecapand the consent text word for word, unticked box, thenPOST /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
| Field | Rule |
|---|---|
trade_id | identifier of a trade open to the API |
service | a value from the trade's services |
other_need | required with “Autre besoin” (3 to 160 characters) |
delay | a label from delays |
place_id | identifier returned by GET /places |
contact | name, phone, email of the person to call back |
message | optional, 2,000 characters at most, no health data |
reference | optional: your reference (e.g. booking number), without personal data |
end_user_ref | optional: stable pseudonym of the user on your side (never an e-mail or a number) |
country, lang | optional: 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.