Platform
ScaiWave ScaiGrid ScaiCore ScaiBot ScaiDrive ScaiKey Models Tools & Services
Solutions
Organisations Developers Internet Service Providers Managed Service Providers AI-in-a-Box
Resources
Support Documentation Blog Downloads
Company
About Research Careers Investment Opportunities Contact
Log in

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.

json
1
2
3
4
5
6
7
8
"carrier": {
  "source": "matched",
  "profile_id": "…", "profile_name": "Example Carrier",
  "settings": {"number_format": "intl00", "country_code": "31", "from_mode": "cli",
               "allowed_ips": "192.0.2.0/24", "max_channels": 10},
  "preview": {"caller_e164": "+31201234567", "from": "sip:0031201234567@sip.example-carrier.com",
              "p_asserted_identity": null, "example_to": "sip:0031201234567@sip.example-carrier.com"}
}

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):

json
1
2
{"state": "registered", "registered": true, "registrar": "sip.example-carrier.com",
 "expires": 300, "next_attempt_at": "2026-10-11T09:14:05+00:00"}

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:

json
1
2
3
4
5
6
7
{
  "host": "sbc.scailabs.ai",
  "egress": {"v4": "203.0.113.10", "v6": "2001:db8::10"},
  "sip": {"port": 5060, "transports": ["UDP", "TCP"], "tls_port": 5061},
  "rtp": {"port_start": 30000, "port_end": 40000, "transport": "UDP"},
  "guidance": "…"
}

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):

json
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
  "voicemail_transcript_enabled": false,
  "phones_allow_international": false,
  "phones_allow_premium": false,
  "phones_max_outbound_calls": 4,
  "recording_mode": "off",
  "recording_internal_calls": false,
  "recording_user_can_stop": true,
  "recording_observers_can_start": false,
  "recording_announcement_text": null,
  "recording_retention_days": 90,
  "recording_transcript_enabled": false,
  "recording_live_captions_enabled": false,
  "recording_captions_without_recording": false,
  "call_language": null,
  "sip_domain_label": "example"
}

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
Updated 2026-10-14 00:46:57 View source (.md) rev 12