Skip to content
KelkiDevelopers

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