Quickstart
Six calls in the sandbox, from the test key to the webhook. In test mode, no real request is created and no e-mail is sent.
1. A test key
The developer account gives you a kk_test_… key, shown only once. The self-service developer space is being prepared: in the meantime, ask for your account at contact@kelki.ai. Keep the key server-side, in an environment variable:
export KELKI_KEY=kk_test_…
2. The trade and its lists
curl -s "https://kelki.ai/api/v1/trades/plombier?country=FR&lang=fr" \
-H "Authorization: Bearer $KELKI_KEY"
The response gives services (closed list, including “Autre besoin”, other need), delays (labels) and consent (consent text and version). If you start from a need in everyday words, call POST /trade-matches first (reference).
3. The place
curl -s "https://kelki.ai/api/v1/places?q=Cr%C3%A9teil&country=FR" \
-H "Authorization: Bearer $KELKI_KEY"
Keep the id of the chosen place, for example fr-creteil-94000.
4. The draft
curl -s https://kelki.ai/api/v1/requests \
-H "Authorization: Bearer $KELKI_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: resa-0042-draft-1" \
-d '{"country":"FR","lang":"fr","trade_id":"plombier","service":"Recherche de fuite",
"delay":"Dès que possible","place_id":"fr-creteil-94000",
"contact":{"name":"Camille Exemple","phone":"+33639980042","email":"camille.exemple@example.com"},
"reference":"resa-2026-0042"}'
201 response: status: "draft", recap and consent. Show the summary, then the consent text word for word with an unticked box (rules). The draft expires after 2 hours.
5. Confirmation by e-mail
Once the person has ticked the box:
curl -s https://kelki.ai/api/v1/requests/req_01JC00000000000000000000RQ/confirmation \
-H "Authorization: Bearer $KELKI_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: resa-0042-confirmation-1" \
-d '{"method":"email","consent_text_version":"v2026-10-18","consent_given":true}'
Status awaiting_confirmation. In production the person receives the “Confirm my request” e-mail; in the sandbox, sending is simulated.
6. Tracking
Declare a webhook endpoint (POST /webhook-endpoints, guide), then move the test request forward:
curl -s https://kelki.ai/api/v1/sandbox/requests/req_01JC00000000000000000000RQ/simulate \
-H "Authorization: Bearer $KELKI_KEY" -H "Content-Type: application/json" \
-d '{"status":"sold"}'
Your endpoint receives a signed request.status_changed event. The same calls in JavaScript and Python: code examples.
Next
- Going live: after approval by Kelki; your code does not change, only the key (
kk_live_…) does (sandbox). - Errors and edge cases: errors, rate limits, idempotency.