Developers
Everything the console does, the API does too.
A versioned public API, real-time events and signed webhooks. This is not a marketing layer over a closed product: the Konvoice administration console consumes exactly these same endpoints.
Principles
Four commitments that matter more than the list of endpoints.
Versioned
/api/v1/ is stable. A breaking change means a new major version, never a silent modification. The old version stays served for twelve months at least.
Traceable
Every request carries a correlation identifier you find again in our logs and in your audit log. A support ticket starts with that number.
Idempotent
Every write accepts an idempotency key. Replaying a request after a network timeout does not create a second user or a second call.
Partitioned
A token belongs to one company and carries explicit scopes. It cannot read beyond them, and a read scope never becomes a write.
REST
Creating a user with their extension.
A single request creates the person, their extension, their device credentials and triggers the provisioning of their phone.
POST /api/v1/users HTTP/1.1
Host: api.konvoice.io
Authorization: Bearer kv_live_…
Idempotency-Key: 4f1c-9a02-b7
{
"display_name": "Amadou Diallo",
"email": "[email protected]",
"site_id": "site_lyon",
"extension": "203",
"role": "agent",
"devices": [
{ "type": "deskphone", "mac": "805e0c1a2b3c" },
{ "type": "mobile" },
{ "type": "web" }
],
"teams": ["support"]
}
Before production
Numbers that answer wrongly, on purpose.
The worst test environment for a telephony integration is a colleague you ring twenty times. The sandbox supplies numbers whose behaviour is predictable — answered, no answer, busy, voicemail, carrier failure — and your tests stop depending on somebody.
- Deterministic scenarios — one number per outcome, always the same.
- Real webhooks — signed, replayable, in the same format as production.
- A correlation identifier on every request, which support can find in our logs.
- No billed calls — the sandbox consumes nothing.
Events
What happens, at the moment it happens.
Events are delivered by signed webhook and by real-time stream. Both carry the same payload, with the same at-least-once delivery guarantee.
| Event | When | Common use |
|---|---|---|
call.ringing | A call starts ringing | Show the customer record before pick-up |
call.answered | Somebody picked up | Start a timer, open a ticket |
call.ended | The call is over | Write the activity into the CRM |
call.missed | Nobody answered | Create a callback task |
recording.ready | The recording is available | Archive it in your own storage |
transcript.ready | The transcript and summary are produced | Feed your analytics tool |
voicemail.received | A voicemail is left | Notify a team |
device.registered | A phone registers | Monitor the estate |
site.link_lost | A site switches to local standalone | Alert your network monitoring |
site.link_restored | A site’s link is restored | Close the alert, check the sync queue |
fraud.route_blocked | A route was cut by the fraud engine | Wake somebody up |
Webhooks
Signed, time-stamped, replayed.
Verify the signature before processing the payload. The timestamp protects against replay, the idempotency key protects against duplicates when we retry.
- HMAC-SHA256 signature over the raw body, with one secret per delivery endpoint.
- Retries with growing backoff for 24 hours, then a failure queue you can inspect.
- Reject a timestamp older than five minutes: that is a replay.
- Answer 2xx quickly and process in the background; we cut off at 10 seconds.
POST /your-endpoint HTTP/1.1
Konvoice-Signature: t=1743158400,
v1=8c1f…d40a
Konvoice-Event-Id: evt_01HZ…
Konvoice-Delivery: 1
{
"type": "call.ended",
"created_at": "2026-03-28T09:20:00Z",
"tenant_id": "ten_8f3c",
"data": {
"call_id": "call_01HZ…",
"direction": "inbound",
"from": "+33478XXXXXX",
"to": "+33472XXXXXX",
"extension": "203",
"duration_s": 214,
"disposition": "answered",
"site_id": "site_lyon",
"handled_locally": true
}
}Our own screens consume nothing but this API. It is the only serious guarantee that it will stay complete.
The day it is missing something, our application stops too
Test environment
Develop without ringing real customers.
A separate environment, with its own tokens, its test numbers and a set of calls you can simulate on demand.
Test numbers
Numbers that answer with a predictable scenario: answered, no answer, busy, voicemail, carrier failure. Your automated tests stop depending on a colleague.
Triggerable events
Emit any event from the list from the console, including a site losing its link, to check that your integration reacts correctly.
Delivery log
Every webhook sent, its response, its latency and its retries. Manually replaying a delivery is one button.
Developer questions
Are there rate limits?
Do you provide an OpenAPI specification?
Can calls be controlled in real time?
Is the API available on an offline site?
Test access, free of charge.
Tell us what you want to build. We open an environment with test numbers and stay reachable throughout your integration.
No commitment. No card number asked for.