Developers / REST APIAll pages
Developers

REST API

Read calls, recordings and transcripts, manage phonebooks, set people's availability and place calls from your own systems. Every key belongs to one organization and only ever sees that organization's data.

Base URL
/api/v1
Authentication
Bearer API key
Format
JSON over HTTPS
Rate limit
120 requests / min / key

Overview

The API is served by the dashboard itself, on the same domain your people sign in to. It reads from the same database the phone system uses, so a call shows up in the API as soon as it shows up in Call history. Placing a call goes through Asterisk, exactly as if the person had dialled it on their phone.

Your Voip9 serverBearer keySQLAMIYour systemCRM · core bankingDashboard/api/v1MariaDBCalls · contactsAsteriskClick-to-call
Your server talks HTTPS to the dashboard; the dashboard reads the database and, for click-to-call, asks Asterisk to ring the phone.

For things you want to be told about the moment they happen (a call ended, a voicemail arrived), use webhooks instead of polling this API.

Quick start

  1. Create a key

    An Admin opens Administration → Integrations → REST API, names the key after the system that will use it (for example CRM production) and picks its scopes. The key is shown once; copy it into your secrets manager.

  2. Make a first request

    List the people in your organization. A 200 answer means the key works.

    Shell
    curl -s "https://voip.yourbank.example/api/v1/users" \  -H "Authorization: Bearer $VOIP9_API_KEY"
  3. Read your calls

    Fetch today's missed calls and page through them with the cursor.

    Shell
    curl -s "https://voip.yourbank.example/api/v1/calls?status=missed&from=2026-11-15T00:00:00Z&limit=50" \  -H "Authorization: Bearer $VOIP9_API_KEY"

Authentication

Send the key in the Authorization header of every request. There are no sessions or cookies.

HTTP
GET /api/v1/calls HTTP/1.1Host: voip.yourbank.exampleAuthorization: Bearer v9k_8mJx2QeL0pV7dN3sK1tRw9yZb4cH6aFq

Keys

  • Keys start with v9k_. Only Admins can create or revoke them.
  • The dashboard stores only a SHA-256 hash of the key. It cannot show a key again: if it is lost, create a new one and revoke the old one.
  • A key belongs to one organization. Every query it runs is limited to that organization; another organization's ids answer 404.
  • The key list shows when each key was last used (updated at most once a minute).
  • Revoking a key takes effect on the next request. Creating and revoking keys is recorded in the audit trail.

Scopes

Each key has one or more scopes. Give each system only what it needs.

ScopeAllows
readEvery GET endpoint: calls, recordings, transcripts, contacts, people, queues, voicemail.
writeCreating, changing and deleting contacts, and setting a person's availability. A write key can also read.
calls:placePlacing calls with POST /calls. This scope does not include reading; add read as well if the system needs both.

Requests and responses

  • Base URL: https://<your dashboard domain>/api/v1. HTTPS only.
  • Send request bodies as JSON with Content-Type: application/json. A body that is not valid JSON answers 400.
  • Successful answers wrap the result in data: an object for one item, an array for a list. DELETE answers 204 with no body.
  • Call times (started_at, received_at) are ISO 8601 in UTC. Availability times (status_since) are UTC in the form YYYY-MM-DD HH:MM:SS.
  • Extensions are 3 to 6 digits starting with 1 to 7, always sent as strings: "1004".

Pagination

GET /calls is paged with a cursor. Ask for up to limit records (default 50, at most 200); if there are more, the answer includes a next_cursor. Pass it back as ?cursor= to get the next, older page. When next_cursor is null you have everything.

Read every call of a dayJavaScript
1const headers = { Authorization: `Bearer ${process.env.VOIP9_API_KEY}` }2const calls = []3let cursor = null4do {5  const url = new URL("https://voip.yourbank.example/api/v1/calls")6  url.searchParams.set("from", "2026-11-14T00:00:00Z")7  url.searchParams.set("to", "2026-11-15T00:00:00Z")8  url.searchParams.set("limit", "200")9  if (cursor) url.searchParams.set("cursor", String(cursor))10  const res = await fetch(url, { headers })11  const page = await res.json()12  calls.push(...page.data)13  cursor = page.next_cursor14} while (cursor)

GET /voicemail takes limit (default 50, at most 200) but no cursor. Contacts, people and queues are returned in full.

Errors

Every error has the same JSON shape, with a stable code you can switch on and a message meant for your logs.

Response · 400 Bad RequestJSON
{ "error": { "code": "invalid_request", "message": "body: Body must be JSON" } }
StatuscodeWhen
400invalid_requestA parameter or body field is missing or wrong, or the body is not JSON. The message lists each problem as field: reason, separated by ; .
401unauthorizedNo Authorization header, or the key is unknown or revoked.
403forbiddenThe key lacks the scope this endpoint needs, e.g. This key has no "write" scope.
404not_foundThe call, contact, extension or recording does not exist in your organization.
429rate_limitedMore than 120 requests in the last minute with this key. The error includes retry_after_seconds.
500server_errorSomething failed on the server. Safe to retry a GET; check before retrying a POST /calls.

Rate limits

Each key may make 120 requests in any 60-second window. Request 121 answers 429 and is not counted, so once older requests leave the window you can continue. There is no Retry-After header; the body says how long to wait.

Response · 429 Too Many RequestsJSON
{ "error": { "code": "rate_limited", "message": "At most 120 requests per minute per key", "retry_after_seconds": 60 } }

Calls

Each item is one call record from the phone system. A simple call has one record; a call that moved through an IVR, a queue or a transfer can have several records that share the same call_id.

List calls

GET/api/v1/calls

Call records of your organization, newest first. Scope: read.

Query parameters

directionstring
inbound, outbound or internal.
statusstring
answered, missed or voicemail. missed also includes busy calls and calls that ended in voicemail.
fromISO 8601
Only calls that started at or after this time. Include the offset.Example: 2026-11-14T00:00:00Z
toISO 8601
Only calls that started before this time.Example: 2026-11-15T00:00:00+05:00
extensionstring
Only calls from, to or answered by this extension.Example: 1004
limitinteger
1 to 200, default 50.
cursorinteger
The next_cursor of the previous page.
Shell
curl -s "https://voip.yourbank.example/api/v1/calls?status=missed&limit=20" \  -H "Authorization: Bearer $VOIP9_API_KEY"
Response · 200 OKJSON
1{2  "data": [3    {4      "id": 48213,5      "call_id": "1794678793.33",6      "started_at": "2026-11-14T13:02:11.000Z",7      "from": "+923001234567",8      "to": "8201",9      "direction": "inbound",10      "status": "missed",11      "duration_seconds": 41,12      "talk_seconds": 0,13      "answered_by": null,14      "recording_url": null,15      "tags": [],16      "note": ""17    }18  ],19  "next_cursor": 4819020}

Call fields

idinteger
Id of this call record. Use it with /calls/{id} and as the cursor.
call_idstring
The call's id, shared by every record of the same call. Also in webhooks and recordings.
started_atstring
ISO 8601, UTC.
fromstring
The calling number or extension.
tostring
The dialled number: an extension, an IVR, a queue or an outside number.
directionstring
inbound, outbound or internal.
statusstring
answered, missed, voicemail, busy or failed.
duration_secondsinteger
Ringing plus talking.
talk_secondsinteger
Talking only; 0 when nobody answered.
answered_bystring | null
The extension that answered, or null.
recording_urlstring | null
Path of the recording, e.g. /api/v1/calls/48213/recording, or null when the call has none.
tagsstring[]
Tags people put on the call.
notestring
The call's note, empty when there is none.

Get one call

GET/api/v1/calls/{id}

One call with its transcript and AI summary. Scope: read.

{id} is either the numeric id or the call_id. With a call_id you get the record of that call that talked longest, usually the one with the recording.

Shell
curl -s "https://voip.yourbank.example/api/v1/calls/1794678793.33" \  -H "Authorization: Bearer $VOIP9_API_KEY"
Response · 200 OKJSON
1{2  "data": {3    "id": 48220,4    "call_id": "1794678793.33",5    "started_at": "2026-11-14T17:53:13.000Z",6    "from": "+923001234567",7    "to": "8201",8    "direction": "inbound",9    "status": "answered",10    "duration_seconds": 64,11    "talk_seconds": 51,12    "answered_by": "1004",13    "recording_url": "/api/v1/calls/48220/recording",14    "tags": ["card blocked", "resolved"],15    "note": "Unblocked after ID check",16    "transcript": [17      { "side": "caller", "start": 0.4, "end": 3.1, "text": "Hi, my card was blocked this morning." },18      { "side": "callee", "start": 3.5, "end": 6.0, "text": "I can help with that. Can you confirm your name?" }19    ],20    "summary": {21      "text": "Caller's debit card was blocked after a failed PIN; the agent unblocked it after verification.",22      "intent": "unblock debit card",23      "topics": ["card blocked", "pin reset"],24      "sentiment": "positive",25      "urgency": "medium",26      "flags": []27    }28  }29}

Extra fields

transcriptarray | null
Who said what, with start and end in seconds. side is caller (the outside person) or callee (your person). Null until the call is transcribed.
summaryobject | null
The AI analysis, when call analysis is on and finished: text, intent, topics, sentiment (positive | neutral | negative), urgency (low | medium | high), flags.

Download a recording

GET/api/v1/calls/{id}/recording

The recording as a stereo WAV: caller on the left channel, your person on the right. Scope: read.

Use the recording_url from a call, or any {id} accepted by /calls/{id}. The answer is audio/wav, not JSON. A call without a recording answers 404 with This call has no recording.

Shell
curl -s "https://voip.yourbank.example/api/v1/calls/48220/recording" \  -H "Authorization: Bearer $VOIP9_API_KEY" \  -o call.wav

Place a call (click-to-call)

POST/api/v1/calls

Rings one of your people first; when they answer, dials the number as if they had called it. Scope: calls:place.

Body

from_extensionstringrequired
The extension that rings first. It must exist in your organization.Example: 1004
tostringrequired
The number to dial once they answer: 2 to 20 digits, * or #, optionally starting with +.Example: +923001234567
Shell
1curl -s -X POST "https://voip.yourbank.example/api/v1/calls" \2  -H "Authorization: Bearer $VOIP9_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{"from_extension":"1004","to":"+923001234567"}'
Response · 202 AcceptedJSON
{ "data": { "status": "ringing", "from_extension": "1004", "to": "+923001234567", "action_id": "a1" } }

The answer comes back at once, before anyone picks up. The extension rings for up to 30 seconds and shows the number it is about to call. The call then goes out through the organization's outbound route, like a call dialled from that phone. When it ends, it appears in call history and is sent as a call.completed webhook.

Your systemYour systemDashboard APIDashboard APIAsteriskAsteriskAgent phone 1004Agent phone 1004CustomerCustomerPOST /callsBearer key, calls:place1Originatering 1004, up to 30 s2202 ringing3INVITEshows +9230012345674answered5dial +923001234567outbound route6Conversationwebhook call.completeda few seconds after hang-up8
Click-to-call: the API answers 202 straight away; the outcome arrives later as a webhook.

Contacts

Phonebooks are personal: every contact belongs to one extension. Names from a person's phonebook show in their call history and on their phone.

Contact fields

idinteger
The contact's id.
extensionstring
Whose phonebook it is in.
namestring
1 to 80 characters.
numberstring
2 to 32 digits, * or #, optionally starting with +.
companystring
Up to 80 characters; empty when not set.
emailstring
A valid address of up to 190 characters, or empty.
favoriteboolean
Shown first in the person's phonebook.

List contacts

GET/api/v1/contacts

One person's phonebook, or every phonebook in the organization. Scope: read.

Query parameters

extensionstring
Only this person's contacts. Without it, every phonebook, sorted by extension then name.Example: 1004
Shell
curl -s "https://voip.yourbank.example/api/v1/contacts?extension=1004" \  -H "Authorization: Bearer $VOIP9_API_KEY"
Response · 200 OKJSON
1{2  "data": [3    { "id": 311, "extension": "1004", "name": "Ali Raza", "number": "+923001234567", "company": "Raza Traders", "email": "ali@razatraders.pk", "favorite": true }4  ]5}

Get a contact

GET/api/v1/contacts/{id}

One contact. Scope: read.

Shell
curl -s "https://voip.yourbank.example/api/v1/contacts/311" \  -H "Authorization: Bearer $VOIP9_API_KEY"
Response · 200 OKJSON
{ "data": { "id": 311, "extension": "1004", "name": "Ali Raza", "number": "+923001234567", "company": "Raza Traders", "email": "ali@razatraders.pk", "favorite": true } }

Create a contact

POST/api/v1/contacts

Adds a contact to one person's phonebook. Scope: write.

Body

extensionstringrequired
Whose phonebook. Must exist in your organization, or the answer is 404.
namestringrequired
1 to 80 characters.
numberstringrequired
The phone number.
companystring
Optional.
emailstring
Optional; empty string for none.
favoriteboolean
Optional, default false.
Shell
1curl -s -X POST "https://voip.yourbank.example/api/v1/contacts" \2  -H "Authorization: Bearer $VOIP9_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{"extension":"1004","name":"Ali Raza","number":"+923001234567","company":"Raza Traders","favorite":true}'
Response · 201 CreatedJSON
{ "data": { "id": 311, "extension": "1004", "name": "Ali Raza", "number": "+923001234567", "company": "Raza Traders", "email": "", "favorite": true } }

Update a contact

PATCH/api/v1/contacts/{id}

Changes only the fields you send. Scope: write.

Any of name, number, company, email, favorite. A contact cannot be moved to another person's phonebook; create a new one instead. The answer is the updated contact.

Shell
1curl -s -X PATCH "https://voip.yourbank.example/api/v1/contacts/311" \2  -H "Authorization: Bearer $VOIP9_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{"number":"+923339876543","favorite":false}'
Response · 200 OKJSON
{ "data": { "id": 311, "extension": "1004", "name": "Ali Raza", "number": "+923339876543", "company": "Raza Traders", "email": "", "favorite": false } }

Delete a contact

DELETE/api/v1/contacts/{id}

Removes the contact. Answers 204 with no body, or 404 if there is no such contact. Scope: write.

Shell
curl -s -X DELETE "https://voip.yourbank.example/api/v1/contacts/311" \  -H "Authorization: Bearer $VOIP9_API_KEY"

People and availability

List people

GET/api/v1/users

Everyone in the organization with their phone and availability. Scope: read.

Shell
curl -s "https://voip.yourbank.example/api/v1/users" \  -H "Authorization: Bearer $VOIP9_API_KEY"
Response · 200 OKJSON
1{2  "data": [3    {4      "extension": "1004",5      "name": "Sara Ahmed",6      "email": "sara@yourbank.com",7      "role": "user",8      "phone_online": true,9      "status": "lunch",10      "status_since": "2026-11-14 13:02:11",11      "calls_30d": 41212    }13  ]14}

Fields

extensionstring
The person's extension.
namestring
Display name.
emailstring | null
Their dashboard sign-in, or null for an extension without a dashboard login.
rolestring | null
admin, supervisor, user, or null without a login.
phone_onlineboolean
At least one desk phone or browser is signed in as this extension right now.
statusstring
Availability: see the table below. available when never set.
status_sincestring | null
When the status was set, UTC YYYY-MM-DD HH:MM:SS. Empty or null when never set.
calls_30dinteger
Calls from or to this extension in the last 30 days.

Get availability

GET/api/v1/users/{ext}/status

One person's availability. Scope: read.

Shell
curl -s "https://voip.yourbank.example/api/v1/users/1004/status" \  -H "Authorization: Bearer $VOIP9_API_KEY"
Response · 200 OKJSON
{ "data": { "extension": "1004", "status": "lunch", "status_since": "2026-11-14 13:02:11" } }

Set availability

PATCH/api/v1/users/{ext}/status

Sets a person's availability, like the status menu in the dashboard. Scope: write.

Body

statusstringrequired
One of the statuses below.Example: break
statusShown asEffect
availableAvailableQueues and calls ring the person.
breakOn a breakPaused in every queue.
lunchOut for lunchPaused in every queue.
trainingIn trainingPaused in every queue.
back_officeBack officePaused in every queue.
dndDo not disturbPaused in every queue.
Shell
1curl -s -X PATCH "https://voip.yourbank.example/api/v1/users/1004/status" \2  -H "Authorization: Bearer $VOIP9_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{"status":"break"}'
Response · 200 OKJSON
{ "data": { "extension": "1004", "status": "break", "status_since": "2026-11-15 09:30:02" } }

Queues

GET/api/v1/queues

Your queues with who is waiting and who can answer, right now. Scope: read.

Shell
curl -s "https://voip.yourbank.example/api/v1/queues" \  -H "Authorization: Bearer $VOIP9_API_KEY"
Response · 200 OKJSON
1{2  "data": [3    { "number": "8201", "name": "Card services", "strategy": "rrmemory", "waiting_now": 3, "agents": 8, "agents_available": 5, "max_wait_seconds": 300 }4  ]5}

Fields

numberstring
The queue's number (82xx).
namestring
The queue's name.
strategystring
How calls are handed out: ringall, rrmemory, leastrecent, fewestcalls or random.
waiting_nowinteger
Callers waiting at this moment.
agentsinteger
People who are members of the queue.
agents_availableinteger
Members who are not paused and have a phone signed in.
max_wait_secondsinteger
How long a caller waits before the queue's fallback.

Voicemail

GET/api/v1/voicemail

Voicemail messages of one mailbox, or of every mailbox, newest first. Scope: read.

Query parameters

mailboxstring
Only this extension's mailbox.Example: 1004
limitinteger
1 to 200, default 50.
Shell
curl -s "https://voip.yourbank.example/api/v1/voicemail?mailbox=1004&limit=20" \  -H "Authorization: Bearer $VOIP9_API_KEY"
Response · 200 OKJSON
1{2  "data": [3    { "id": "1794680560-00000003", "mailbox": "1004", "folder": "new", "from": "+923001234567", "received_at": "2026-11-14T18:02:40.000Z", "duration_seconds": 18 }4  ]5}

folder is new for messages nobody has listened to yet and heard otherwise. from is the caller's number.

Security notes

  • Keys are stored hashed; the dashboard cannot show a key again.
  • Every key creation and revocation is in the audit trail, with the Admin who did it.
  • Recordings served through the API are built from the same files the dashboard plays, so your retention settings apply to both.
  • Store the key in a secrets manager or environment variable, never in source code.

Next steps