Docs / Reference
API and webhooks
Other software can work with Onyx Voice: a CRM can look up and route callers, a script can add extensions, a reporting tool can read the call history. Onyx Voice has a JSON API over HTTPS (the same one the web console uses), API keys to sign in with it, and webhooks that tell your software about calls and voicemail as they happen. This chapter covers creating keys, calling the API, the main endpoints, and receiving webhooks.
Everything here is on the Integrations (API) page, under Connections in the console.
API keys
An API key signs a script in without a password. There are two kinds:
| Key | Made by | Acts as |
|---|---|---|
| A tenant key | A tenant administrator, on Integrations (API) | An administrator of that tenant |
| A system key | A system administrator, card System API keys | A system administrator: every tenant and the server settings |
A key can be Read-only: it reads everything its kind may read and is refused (HTTP 403) when it tries to change anything. Use read-only keys for reporting and lookups.
To create one:
- Open Integrations (API).
- Under API keys, type what will use it under What uses it, for example
HubSpot sync, tick Read-only if it only reads, and click Create key. - Copy the key now. It looks like
onyx_followed by 48 characters, and it is shown only once: Onyx Voice keeps only its hash.
The list shows each key's first characters, its rights, when it was last used and who made it. Delete stops a key at once. A switched-off tenant's keys stop working too. Keys do not need two-factor sign-in, so treat them like passwords: one key per program, read-only where possible, and delete keys nobody uses.
From the command line: onyx apikey add "HubSpot sync" --tenant acme --read-only, onyx apikey list --tenant acme, onyx apikey delete <id> --tenant acme (without --tenant, the commands are for system keys).
Calling the API
Send the key in the Authorization header, and JSON in request bodies:
curl -H "Authorization: Bearer onyx_3f9c..." https://pbx.example.com/api/v1/admin/t/acme/numbers
- Every address starts with
https://and the server's name, then/api/v1/admin. Tenant addresses have/t/<tenant code>/in them. - Answers are JSON. Failures have an HTTP status and a body like
{"error": "Extension 109 does not exist in acme.", "code": "not-found"}: 400 for something wrong in the request, 401 for a missing or unknown key, 403 for something the key may not do, 404 for something that does not exist. - Changes take effect at once, as in the console, and show in Change history as made by
api:<key name>. - Requests count towards the server's flood protection like any other (see Security); a script that makes many requests should pause between them.
Main endpoints
The console uses the same API, so everything it shows or changes can be done with a key. These are the ones integrations use most (acme stands for the tenant code):
| What | Method and address | Body or answer |
|---|---|---|
| All numbers (extensions, groups, queues, menus) | GET /api/v1/admin/t/acme/numbers | A list with number, kind, name, email, enabled, dnd |
| One number in detail | GET /api/v1/admin/t/acme/numbers/101 | The extension, its phones and settings |
| Create an extension | POST /api/v1/admin/t/acme/extensions | {"number": "105", "name": "Pat Lee", "email": "[email protected]"}; the answer has the phone's SIP credentials |
| Change an extension | PATCH /api/v1/admin/t/acme/extensions/105 | Any of name, email, outboundCallerId, voicemailEnabled, ringSeconds, record, missedCallEmail |
| A person's status | GET, PUT /api/v1/admin/t/acme/extensions/105/status | {"status": "away"} sets it; see Status profiles |
| Inbound routes (phone numbers) | GET /api/v1/admin/t/acme/inbound | Each number and where it rings |
| Call history | GET /api/v1/admin/calls?tenant=acme&q=6125550199&limit=50 | Calls, newest first; before=<id> for older ones |
| What happened on a call | GET /api/v1/admin/calls/<id>/story | {"lines": [{"at": "...", "text": "rang 101 Ada: answered, 2 min 5 s talk"}]} |
| A call's recording | GET /api/v1/admin/calls/<id>/recording | The WAV file |
| Block a caller | POST /api/v1/admin/t/acme/callers/block | {"number": "6125550199", "note": "spam"} |
| Contacts | GET, POST /api/v1/admin/t/acme/contacts | Names callers are shown with; see Contacts and directory sync |
| Queue status | GET /api/v1/admin/t/acme/callcentre | Who is waiting, which agents are free |
To see the exact fields of anything the console does, open the browser's developer tools (Network tab) while doing it in the console: the request and its JSON are the API call.
Webhooks
A webhook is an address of yours that Onyx Voice sends a POST to when something happens:
| Event | Sent when |
|---|---|
call.ended | Any call of the tenant ends (incoming, outgoing or between colleagues) |
call.missed | An incoming call ended without anyone answering it |
voicemail.new | A new voicemail message arrives in a mailbox |
call.transcribed | A recorded call of a tenant with call insights was transcribed: the transcript, and with summaries on the summary, sentiment (1-5), topics and follow-ups |
To add one, on Integrations (API) under Webhooks, type the address (https://...), tick the events and click Add webhook. Click Test to send a ping event and see whether your receiver answered; the Last delivery column shows how the last one went. From the command line: onyx webhook add acme https://crm.example.com/hook --events call.missed,voicemail.new.
Each request is a JSON body like:
{
"event": "call.missed",
"delivery": "9b2f0c1e4c6d4f2a8e1d7b3a5c9e0f12",
"at": "2026-10-21T15:04:12Z",
"tenant": "acme",
"data": {
"id": "1729523031.118", "direction": "inbound", "from": "16125557777", "callerName": "Pat Customer",
"to": "600", "did": "16125550100", "startedAt": "2026-10-21T15:03:51Z", "endedAt": "2026-10-21T15:04:07Z",
"answered": false, "answeredBy": null, "talkSeconds": 0, "recorded": false, "legs": 3
}
}
voicemail.new has data with mailbox, newMessages, from, receivedAt, seconds and messageId. Calls are sent about 5 seconds after they end, once all their parts are known.
The headers say what it is and prove it came from your server:
X-Onyx-Event: the event.X-Onyx-Delivery: an id for this delivery.X-Onyx-Signature:sha256=and the HMAC-SHA256 of the exact body, keyed with the webhook's secret (Copy secret on the page). Compute the same over the body you received and compare before trusting it.
For example, in Python:
import hashlib, hmac
def genuine(body: bytes, header: str, secret: str) -> bool:
expected = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, header)
Answer with any 2xx status within 5 seconds. A failed delivery is tried once more 30 seconds later; after that it is dropped and shown under Last delivery.
CRM lookup
Under CRM lookup, give your CRM's search address with {number} where the caller's number goes, for example https://app.hubspot.com/contacts/12345/search?query={number}. The portal then shows Look up next to an incoming call in the softphone and next to calls in Recent calls; it opens the caller in the CRM in a new tab. From the command line: onyx tenant crm acme "https://crm.example.com/search?q={number}" (--off removes it).