API Reference
Base URL: https://scaigrid.scailabs.ai/v1/modules/scaidial. Authenticate with a ScaiGrid API key or user token (Authorization: Bearer …). Two surfaces:
- Admin (
/…) — tenant-wide configuration and call control. Every route needs the module permission in its section (permissions); tenant and partner admins hold all of them. - Portal (
/me/…) — a user's own extensions, voicemail and calls, by extension role.
Responses use the ScaiGrid envelope: {"status": "success", "data": …, "meta": {…}}, or on error {"status": "error", "error": {"code": "…", "message": "…"}, "meta": {…}}. ScaiDial error codes start with scaidial. (for example scaidial.call_ended 409, scaidial.transfer_declined 409, scaidial.leg_not_found 404).
Trunks — scaidial:trunks:manage#
| Method + path | Does |
|---|---|
GET /trunks |
List the tenant's trunks |
POST /trunks |
Create (body below); provisioned on the ScaiLabs SBC |
PATCH /trunks/{id} |
Update any field; re-provisions |
DELETE /trunks/{id} |
Delete; fails while DIDs use it |
POST /trunks/{id}/resync |
Retry provisioning after sync_status: "error" |
GET /trunks/{id}/registration |
Live registration with the carrier (below) |
POST /trunks/probe |
Check the SIP service is reachable before saving |
Trunk body:
| Field | Notes |
|---|---|
name |
Label |
sip_server_address, sip_server_port |
The carrier's SIP server and port (usually 5060, or 5061 for TLS) |
sip_transport |
udp, tcp or tls |
sip_auth_mode |
credentials (registers with username/password) or ip_whitelist (the carrier trusts the SBC's address) |
sip_auth_username, sip_auth_password |
For credentials. The password is stored encrypted and never returned (sip_auth_password_set tells you one is set) |
sip_inbound_numbers |
E.164 numbers the carrier delivers on this trunk |
sip_media_encryption |
disabled, allowed or required |
default_caller_id_e164 |
Caller ID for outside calls when the extension sets none |
carrier_profile_id |
The carrier profile to use (see below); "" or omitted = picked automatically from sip_server_address |
carrier_overrides |
Per-trunk overrides of the profile: number_format, country_code, from_mode, allowed_ips, max_channels. A null field inherits from the profile; {} clears all overrides |
notes, enabled |
Free text; on/off |
Responses add id, sync_status (pending / synced / error), sync_last_error, created_at, and carrier: the settings in effect and what the carrier receives.
1 2 3 4 5 6 7 8 | |
source is assigned (the trunk chose the profile), matched (by the SIP server's host) or generic (no profile applies).
Carrier profiles#
A carrier profile says how a carrier wants numbers and the caller ID presented. ScaiLabs maintains them for carriers we have verified; a trunk uses the profile it chose, otherwise the one matching its SIP server, otherwise the generic settings (E.164, caller ID in From, any source address, 10 calls).
| Setting | Values |
|---|---|
number_format |
e164 (+31201234567), e164_noplus (31201234567), intl00 (0031201234567), national (0201234567) |
country_code |
Used to read and write national numbers, e.g. 31 |
from_mode |
cli: the caller ID goes in From. account: the account username goes in From and the caller ID in P-Asserted-Identity; only for carriers that read the caller ID from that header |
allowed_ips |
The carrier's source addresses (IPs/CIDRs, comma-separated); calls from elsewhere are refused. Required for ip_whitelist trunks |
max_channels |
Simultaneous calls on the trunk |
| Method | Does |
|---|---|
GET /carrier-profiles |
The profiles (items), the generic settings (generic) and whether you may edit them (can_edit) |
POST /carrier-profiles, PATCH /carrier-profiles/{id}, DELETE /carrier-profiles/{id} |
Super admins only. Fields: name, description, match_hosts (host names; parent domains match their sub-domains) and the settings above. Saving re-provisions the trunks that use the profile; deleting fails while a trunk has chosen it |
Registration (GET /trunks/{id}/registration):
1 2 | |
state: registered, registering, pending (not tried yet), failed (rejected or no answer; retried), disabled, not_loaded, unknown (SBC unreachable), or not_applicable (IP-based trunks don't register).
GET /network-info#
What a carrier that filters by source address needs to allow:
1 2 3 4 5 6 7 | |
Numbers (DIDs) — scaidial:trunks:manage#
| Method + path | Does |
|---|---|
GET /dids |
List |
POST /dids |
{e164, trunk_id, dialplan_id, label?} |
PATCH /dids/{id} |
{trunk_id?, dialplan_id?, label?, enabled?} |
DELETE /dids/{id} |
Delete |
Extensions — scaidial:extensions:manage#
| Method + path | Does |
|---|---|
GET /extensions |
List |
POST /extensions |
Create (body below) |
PATCH /extensions/{id} |
Update any field below, plus dnd, dnd_until, enabled |
DELETE /extensions/{id} |
Delete |
GET /extensions/{id}/sip-account |
Phone login and current registrations (sip_endpoint only) — see phones |
POST /extensions/{id}/sip-account/rotate |
New phone password; logs out registered phones |
POST /extensions/{id}/sip-account/sync |
Re-create the phone login |
GET /extensions/{id}/grants |
Who has a role on the extension |
POST /extensions/{id}/grants |
{user_id | group_id, role}; role owner, manage, answer or observe |
DELETE /extensions/{id}/grants/{grant_id} |
Remove a grant |
GET /extensions/{id}/forward-rules |
List forward rules |
POST /extensions/{id}/forward-rules |
{condition, forward_to, condition_params?, priority?} |
DELETE /extensions/{id}/forward-rules/{rule_id} |
Delete a forward rule |
Extension body:
| Field | Notes |
|---|---|
number |
Internal number, e.g. 201 |
type |
wave (a ScaiWave user), sip_endpoint (desk phones / softphones), bot (a ScaiBot voice agent), voicemail (a mailbox only), external (an outside number) |
target_ref |
wave: the user's ScaiGrid id · bot: the bot id · external: the E.164 number · not used for sip_endpoint |
display_name |
Shown to callers and in the directory |
ring_timeout_s |
Seconds to ring before the walk moves on |
timeout_action, timeout_forward_to |
wave only: voicemail, forward (to an extension number) or hangup |
assistant_pickup_after_s |
wave only: hint for an assistant taking over |
voicemail_greeting_text |
Spoken greeting; empty = the default |
outbound_caller_id_e164 |
Caller ID for outside calls; one of your numbers |
moh_playlist_id |
Music on hold for calls this extension holds; "" = tenant default |
Forward-rule condition: always, busy, no_answer, time (condition_params with a time window) or caller (condition_params.match). forward_to is an extension number.
Dialplans — scaidial:dialplan:manage#
| Method + path | Does |
|---|---|
GET /dialplans · POST /dialplans |
List · create {name, description?} |
PATCH /dialplans/{id} · DELETE /dialplans/{id} |
Rename / describe · delete |
GET /dialplans/{id}/rules |
Rules in priority order |
POST /dialplans/{id}/rules |
{priority, label?, match_type, match_params, action_type, action_params} |
PATCH /dialplans/{id}/rules/{rule_id} |
Partial update, re-validated |
DELETE /dialplans/{id}/rules/{rule_id} |
Delete |
GET /dialplan-pickers |
Everything a rule editor needs: DIDs, extensions, bots, users (also with scaidial:extensions:manage) |
Match and action shapes: dialplans.
Calls and call control — scaidial:calls:observe#
| Method + path | Does |
|---|---|
GET /calls/active |
Calls ringing, active or held, with their legs |
GET /calls/{id} |
One call with its legs |
GET /calls/history |
Ended calls. Filters: extension_id, from_e164, end_reason, started_after, started_before (ISO 8601), limit (≤ 500), cursor_started_at (from next_cursor_started_at) |
POST /legs/{id}/hangup |
Remove that party |
POST /legs/{id}/hold · /unhold |
Hold with music on hold · take off hold |
POST /legs/{id}/transfer |
Blind transfer by SIP REFER {to_extension, mode: "blind"} |
POST /legs/{id}/consult |
Start an attended transfer from your leg {to} |
GET /transfers/{consult_id} |
Its state |
POST /transfers/{consult_id}/complete · /cancel |
Hand over · back to the caller |
POST /calls/merge |
{keep_leg_id, merge_leg_id} — merge two of your calls |
GET /legs/{id}/conference |
Merged calls, focus, who is on hold |
POST /legs/{id}/conference/focus |
{focus: "all" | "kept" | "none" | "<bridge_id>"} |
POST /legs/{id}/conference/drop |
{bridge_id} — hang up one merged call |
POST /legs/{id}/speak |
{text, voice_id?, language?} — say text into the call |
Details and state tables: call control.
Voicemail — scaidial:extensions:manage#
| Method + path | Does |
|---|---|
GET /voicemail |
Messages, newest first. extension_id, only_unheard, limit (≤ 500) |
GET /voicemail/{id}/audio |
The recording (audio/wav) |
POST /voicemail/{id}/listened |
Mark listened |
DELETE /voicemail/{id} |
Delete with the recording |
See voicemail.
Call recordings — scaidial:recordings:read / :manage#
| Method + path | Does |
|---|---|
GET /recordings |
Recordings, newest first. call_id, extension_id, before, limit (≤ 500) |
GET /recordings/{id} |
One recording |
GET /recordings/{id}/audio |
The audio (audio/ogg, supports Range) |
GET /recordings/{id}/transcript |
Transcript turns, full text and summary |
DELETE /recordings/{id} |
Delete the audio (:manage) |
PUT /recordings/{id}/legal-hold · DELETE /recordings/{id}/legal-hold |
Legal hold on / off (:manage) |
POST /recordings/erase |
{"e164"}: delete every recording that number took part in; returns deleted, deleted_ids, legal_hold_ids, live_ids (:manage) |
POST /calls/{call_id}/recording/{start|pause|resume|stop} |
Control a call's recording (:manage) |
POST /calls/{call_id}/captions/{start|stop} |
Live captions on/off (:manage) |
See call recording.
Music on hold — any tenant user#
Admins (scaidial:trunks:manage) manage tenant playlists; everyone manages their own. Endpoints under /moh/…: see music on hold.
Tenant policy — scaidial:trunks:manage#
GET /policy · PATCH /policy (send only what changes):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | |
recording_mode: off, on_demand or always. recording_consent: announce or announce_and_confirm (outside callers press 1). call_language: nl, en, or null for the platform default; "" clears it, as for recording_announcement_text. See call recording.
sip_domain_label is read-only: the tenant's phone domain is <label>.sip.scailabs.ai.
End-user portal — /me/…#
| Method + path | Role on the extension |
|---|---|
GET /me/extensions |
any; each with your role |
PATCH /me/extensions/{id} |
owner: display_name, dnd, dnd_until, ring_timeout_s, voicemail_greeting_text |
GET /me/voicemail · GET /me/voicemail/{id}/audio · POST /me/voicemail/{id}/listened · DELETE /me/voicemail/{id} |
owner or manage |
GET /me/recordings · GET /me/recordings/{id} · GET /me/recordings/{id}/audio · GET /me/recordings/{id}/transcript |
any role on an extension in the call, or you placed it |
DELETE /me/recordings/{id} |
owner or manage |
POST /me/calls/{call_id}/recording/{start|pause|resume|stop} |
you placed the call, or owner / manage / answer on an extension in it (observe when the tenant allows) |
GET /me/extensions/{id}/forward-rules · POST … · DELETE …/{rule_id} |
owner |
GET /me/calls/history |
calls you placed or that touched your extensions |
POST /me/click-to-call |
owner of from_extension_id. Body {to, from_extension_id}; returns {call_id, leg_id, livekit_url, livekit_token, room_name} for the browser to join |