Skip to main content
API docs by Redocly

DialStack API (1.0.0)

Download OpenAPI specification:Download

DialStack API Support: info@dialstack.ai URL: https://docs.dialstack.ai/api License: Proprietary

DialStack — Business Voice for Vertical SaaS

Authentication

DialStack supports three authentication methods:

Platform API Keys (Backend)

For server-side integrations, use your secret API key (starts with sk_live_) in the Authorization header.

Example: Authorization: Bearer sk_live_YOUR_SECRET_KEY

Session Tokens (Embedded Components)

For embedded voice components in your frontend, create a session using the Account Session API and use the client_secret JWT token in the Authorization header.

Example: Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Sessions are account-scoped and expire after 1 hour.

User Tokens (Softphones & User-Facing Apps)

For client-side applications where end users interact directly (softphones, call history, voicemail), authenticate users via POST /v1/user_sessions and use the returned user token.

Example: Authorization: Bearer eyJhbGciOiJFZERTQSIs...

User tokens are scoped to a single user within an account and grant access to the WebRTC signalling channel, call history, voicemails, and presence. See the Authentication guide for setup details.

Account Context

Most API endpoints require an account context. This is specified differently depending on the authentication method:

Platform API Keys

Include the DialStack-Account header with the account ID:

DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41

Session Tokens

The account is automatically derived from the JWT claims. No header is needed.

Pagination

All list API methods support URL-based cursor pagination. Results are returned in reverse chronological order.

Request Parameters

  • limit - Number of objects to return (1-100, default 10)
  • page - Opaque cursor token (only used when following pagination URLs)

Response Structure

List responses include:

  • object - Always "list"
  • url - The endpoint URL
  • next_page_url - URL to fetch the next page (null if no more pages)
  • previous_page_url - URL to fetch the previous page (null if on first page)
  • data - Array of objects

Usage

To paginate, simply follow the URLs provided in next_page_url and previous_page_url. Do not construct pagination URLs manually - the cursor format is opaque and may change.

Expanding Responses

Some endpoints support the expand[] parameter to include related resources inline. Without expansion, the related data is omitted from the response.

For example, to include extensions when listing users:

GET /v1/users?expand[]=extensions

The expanded field appears as a nested list object:

{
  "id": "user_01h2xcejqtf2nbrexx3vqjhp42",
  "name": "Dr. Alice Smith",
  "extensions": {
    "object": "list",
    "data": [
      {
        "number": "105",
        "target": "user_01h2xcejqtf2nbrexx3vqjhp42",
        "status": "active",
        "created_at": "2025-10-18T10:00:00Z",
        "updated_at": "2025-10-18T10:00:00Z"
      }
    ]
  }
}

Expandable fields are noted in endpoint descriptions.

Base URL

  • https://api.dialstack.ai

Voice Apps

For building programmable voice applications with webhooks and real-time audio streaming, see the Voice Apps Guide.

Routing Targets

A routing target is a resource that can receive calls. The following resource types are valid routing targets:

  • User — rings all of the user's registered devices (desk phones, softphones)
  • Voice App — delivers the call via webhook notification for programmatic control or monitoring
  • Dial Plan — routes the call through a dial plan graph
  • Ring Group — rings all group members simultaneously
  • Shared Voicemail — sends the call directly to a shared voicemail box

Resource IDs

All resource IDs in the API are opaque strings of at most 255 characters. Do not parse or make assumptions about their format — treat them as identifiers to store and pass back to the API.

Accounts

Account (customer organization) management. These endpoints operate at the platform level and don't require the DialStack-Account header.

Create a new account

Creates a new account (customer organization) within the platform. Accounts represent individual customer organizations (e.g., Jones Chiropractic) that use the vSaaS platform.

Authorizations:
BearerAuth
Request Body schema: application/json
required
email
string <email>

Email address for the account

name
string

Company or organization name

phone
string

Phone number in E.164 format

primary_contact_name
string

Name of the primary contact

object (AccountConfig)

Account-level configuration settings

Responses

Response Schema: application/json
id
required
string

Unique identifier

email
string or null <email>

Email address for the account (optional)

name
string or null

Company or organization name

phone
string or null

Phone number in E.164 format

primary_contact_name
string or null

Name of the primary contact

required
object (AccountConfig)

Account-level configuration settings

default_outbound_did_id
string or null

ID of the phone number to use as the default outbound caller ID. When null, the first outbound-enabled number is used.

hold_music_clip_id
string or null

ID of an audio clip on the account played in a loop to held callers (regular SIP hold, parking, queue wait). When null, callers hear the platform default hold music.

provisioning_base_url
string or null

The full provisioning base URL for this account. Phones use this URL prefix for auto-provisioning configuration files.

Address (object) or null

The account's billing/business address, geocoded via address validation. Null if not set.

created_at
required
string <date-time>

Timestamp when it was created

updated_at
string <date-time>

Timestamp when it was last updated

Request samples

Content type
application/json
Example
{
  • "email": "contact@example.com"
}

Response samples

Content type
application/json
{
  • "id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  • "email": "contact@example.com",
  • "config": { },
  • "created_at": "2025-10-18T10:00:00Z",
  • "updated_at": "2025-10-18T10:00:00Z"
}

List all accounts

List all accounts for the authenticated platform. Results are returned in reverse chronological order (newest first).

Authorizations:
BearerAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

Number of objects to return. Defaults to 10. Maximum is 100.

Responses

Response Schema: application/json
object
required
string (ListObject)
Value: "list"

String representing the object's type. Always "list" for list responses.

url
required
string (ListUrl)

The URL for accessing this list.

next_page_url
required
string or null (NextPageUrl)

URL to fetch the next page of results. If null, there are no more pages. The URL includes all necessary parameters including the pagination cursor.

previous_page_url
required
string or null (PreviousPageUrl)

URL to fetch the previous page of results. If null, this is the first page. The URL includes all necessary parameters including the pagination cursor.

required
Array of objects (Account)

Request samples 

curl -X GET \
  'https://api.dialstack.ai/v1/accounts?limit=10' \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "object": "list",
  • "url": "/v1/accounts",
  • "next_page_url": null,
  • "previous_page_url": null,
  • "data": [
    ]
}

Get account details

Retrieve a specific account by ID.

Authorizations:
BearerAuth
path Parameters
account_id
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier

Responses

Response Schema: application/json
id
required
string

Unique identifier

email
string or null <email>

Email address for the account (optional)

name
string or null

Company or organization name

phone
string or null

Phone number in E.164 format

primary_contact_name
string or null

Name of the primary contact

required
object (AccountConfig)

Account-level configuration settings

default_outbound_did_id
string or null

ID of the phone number to use as the default outbound caller ID. When null, the first outbound-enabled number is used.

hold_music_clip_id
string or null

ID of an audio clip on the account played in a loop to held callers (regular SIP hold, parking, queue wait). When null, callers hear the platform default hold music.

provisioning_base_url
string or null

The full provisioning base URL for this account. Phones use this URL prefix for auto-provisioning configuration files.

Address (object) or null

The account's billing/business address, geocoded via address validation. Null if not set.

created_at
required
string <date-time>

Timestamp when it was created

updated_at
string <date-time>

Timestamp when it was last updated

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/accounts/acct_01h2xcejqtf2nbrexx3vqjhp41 \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  • "email": "contact@example.com",
  • "name": "Acme Corp",
  • "phone": "+12125550100",
  • "primary_contact_name": "Jane Doe",
  • "config": {
    },
  • "default_outbound_did_id": "string",
  • "hold_music_clip_id": "string",
  • "provisioning_base_url": "https://prov.netvoice.io/a/abc12345",
  • "billing_address": {
    },
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

Update account

Update account details.

Authorizations:
BearerAuth
path Parameters
account_id
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier

Request Body schema: application/json
required
email
string <email>

Email address for the account

name
string

Company or organization name

phone
string

Phone number in E.164 format

primary_contact_name
string

Name of the primary contact

object (AccountConfig)

Account-level configuration settings

default_outbound_did_id
string

ID of the phone number to use as the default outbound caller ID. Send null to clear.

hold_music_clip_id
string or null

ID of the audio clip played as hold music. Send null to clear (uses platform default).

AddressInput (object) or null

Billing/business address. When present, the address is geocoded via address validation. Send null to clear. Omit to leave unchanged.

Responses

Response Schema: application/json
id
required
string

Unique identifier

email
string or null <email>

Email address for the account (optional)

name
string or null

Company or organization name

phone
string or null

Phone number in E.164 format

primary_contact_name
string or null

Name of the primary contact

required
object (AccountConfig)

Account-level configuration settings

default_outbound_did_id
string or null

ID of the phone number to use as the default outbound caller ID. When null, the first outbound-enabled number is used.

hold_music_clip_id
string or null

ID of an audio clip on the account played in a loop to held callers (regular SIP hold, parking, queue wait). When null, callers hear the platform default hold music.

provisioning_base_url
string or null

The full provisioning base URL for this account. Phones use this URL prefix for auto-provisioning configuration files.

Address (object) or null

The account's billing/business address, geocoded via address validation. Null if not set.

created_at
required
string <date-time>

Timestamp when it was created

updated_at
string <date-time>

Timestamp when it was last updated

Request samples

Content type
application/json
{
  • "email": "contact@example.com",
  • "name": "Acme Corp",
  • "phone": "+12125550100",
  • "primary_contact_name": "Jane Doe",
  • "config": {
    },
  • "default_outbound_did_id": "string",
  • "hold_music_clip_id": "string",
  • "billing_address": {
    }
}

Response samples

Content type
application/json
{
  • "id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  • "email": "contact@example.com",
  • "name": "Acme Corp",
  • "phone": "+12125550100",
  • "primary_contact_name": "Jane Doe",
  • "config": {
    },
  • "default_outbound_did_id": "string",
  • "hold_music_clip_id": "string",
  • "provisioning_base_url": "https://prov.netvoice.io/a/abc12345",
  • "billing_address": {
    },
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

Delete account

Delete an account and all associated users, endpoints, and call logs. This operation is irreversible. Active calls will be terminated.

Authorizations:
BearerAuth
path Parameters
account_id
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier

Responses

Request samples 

curl -X DELETE \
  https://api.dialstack.ai/v1/accounts/acct_01h2xcejqtf2nbrexx3vqjhp41 \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "error": "Invalid request body",
  • "code": "validation_error",
  • "details": { }
}

Sessions

Account session management for embedded components. Sessions provide scoped authentication for frontend components. Requires a platform API key — session tokens cannot be used to create new sessions.

Create an account session

Creates a session with account-scoped access. Sessions expire after 1 hour. The session token is scoped to the specified components — it can only access API endpoints required by those components.

The account and components are specified in the request body.

Authorizations:
BearerAuth
Request Body schema: application/json
required
account
required
string

Account identifier

required
object

Components to enable for this session. At least one component must have enabled: true. Each key is a component name and the value configures that component.

Responses

Response Schema: application/json
account_id
required
string

Account identifier for the created session

client_secret
required
string (ClientSecret)

JWT token for account-scoped authentication

expires_at
required
string <date-time> (SessionExpiresAt)

When the session expires

Request samples

Content type
application/json
{
  • "account": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  • "components": {
    }
}

Response samples

Content type
application/json
{
  • "account_id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  • "client_secret": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2NvdW50X2lkIjoiYWNjdF8wMWgyeGNlanF0ZjJuYnJleHgzdnFqaHA0MSIsImp0aSI6IjAxaDJ4Y2VqcXRmMm5icmV4eDN2cWpocDQ2IiwiZXhwIjoxNzI2NzU3MjAwfQ.1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0t1u2",
  • "expires_at": "2025-11-13T15:00:00Z"
}

Create a user session

Mints a short-lived JWT scoped to a single DialStack user. The returned client_secret is used by the WebRTC client SDK to authenticate to the signalling WebSocket and /v1/me/* REST routes.

Sessions default to a 1-hour lifetime and may not exceed 24 hours. The user must already exist under an account owned by the calling platform.

Authorizations:
BearerAuth
Request Body schema: application/json
required
user
required
string <= 255 characters

Identifier of the DialStack user this token will authenticate as. The user must already be provisioned via POST /v1/users and belong to an account owned by the calling platform.

ttl_seconds
integer [ 0 .. 86400 ]

Requested token lifetime in seconds. Defaults to 3600 (1 hour) when omitted or zero. Values above 86400 (24 hours) are rejected.

Responses

Response Schema: application/json
user
required
string

Identifier of the user the session token authenticates as

account
required
string

Identifier of the account that owns the user

client_secret
required
string (ClientSecret)

JWT token for account-scoped authentication

expires_at
required
string <date-time> (SessionExpiresAt)

When the session expires

Request samples

Content type
application/json
{
  • "user": "user_01h2xcejqtf2nbrexx3vqjhp42",
  • "ttl_seconds": 3600
}

Response samples

Content type
application/json
{
  • "user": "user_01h2xcejqtf2nbrexx3vqjhp42",
  • "account": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  • "client_secret": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2NvdW50X2lkIjoiYWNjdF8wMWgyeGNlanF0ZjJuYnJleHgzdnFqaHA0MSIsImp0aSI6IjAxaDJ4Y2VqcXRmMm5icmV4eDN2cWpocDQ2IiwiZXhwIjoxNzI2NzU3MjAwfQ.1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0t1u2",
  • "expires_at": "2025-11-13T15:00:00Z"
}

Users

User (people) management. Requires account context via DialStack-Account header or session token.

Create a new user

Create a new user within the account. Users represent people who have phone service. Each user can have multiple endpoints (devices).

Authorizations:
BearerAuthSessionAuth
header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
name
string or null (EntityName) [ 1 .. 255 ] characters

Display name

email
string <email>

Email address (optional)

Responses

Response Schema: application/json
id
required
string

Unique identifier

name
string or null [ 1 .. 255 ] characters

Display name

email
string or null <email>

Email address (optional)

account_role
string or null
Enum: "account_admin" null

The user's role within the account (null for regular users)

outbound_caller_id_did_id
string or null

ID of the phone number to use as this user's outbound caller ID, overriding the account default. When null, the account default is used.

voicemail_pin
string or null

Numeric PIN for remote voicemail access (4-10 digits). When null, no PIN is set.

object (UserConfig)

User-level configuration settings

object

List of extensions assigned to this user. Only included when expand[]=extensions is requested.

created_at
string <date-time>

Timestamp when it was created

updated_at
string <date-time>

Timestamp when it was last updated

Request samples

Content type
application/json
{
  • "name": "Dr. Alice Smith",
  • "email": "alice@spineline.dev"
}

Response samples

Content type
application/json
{
  • "id": "user_01h2xcejqtf2nbrexx3vqjhp42",
  • "name": "Dr. Alice Smith",
  • "email": "alice@spineline.dev",
  • "created_at": "2025-10-18T10:00:00Z",
  • "updated_at": "2025-10-18T10:00:00Z"
}

List all users

List all users for the account. Results are returned in reverse chronological order (newest first).

Expandable fields: extensions — includes the list of extensions assigned to each user.

Authorizations:
BearerAuthSessionAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

Number of objects to return. Defaults to 10. Maximum is 100.

search
string

Filter users by name or email (case-insensitive partial match)

expand[]
Array of strings
Items Value: "extensions"

Related resources to include inline. Supported values: extensions.

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
object
required
string (ListObject)
Value: "list"

String representing the object's type. Always "list" for list responses.

url
required
string (ListUrl)

The URL for accessing this list.

next_page_url
required
string or null (NextPageUrl)

URL to fetch the next page of results. If null, there are no more pages. The URL includes all necessary parameters including the pagination cursor.

previous_page_url
required
string or null (PreviousPageUrl)

URL to fetch the previous page of results. If null, this is the first page. The URL includes all necessary parameters including the pagination cursor.

required
Array of objects (User)

Request samples 

curl -X GET \
  'https://api.dialstack.ai/v1/users?limit=10&search=SOME_STRING_VALUE&expand%5B%5D=SOME_ARRAY_VALUE' \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "object": "list",
  • "url": "/v1/users",
  • "next_page_url": null,
  • "previous_page_url": null,
  • "data": [
    ]
}

Get user details

Retrieve a specific user by ID.

Expandable fields: extensions — includes the list of extensions assigned to this user.

Authorizations:
BearerAuthSessionAuth
path Parameters
user_id
required
string
Example: user_01h2xcejqtf2nbrexx3vqjhp42

User identifier

query Parameters
expand[]
Array of strings
Items Value: "extensions"

Related resources to include inline. Supported values: extensions.

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
id
required
string

Unique identifier

name
string or null [ 1 .. 255 ] characters

Display name

email
string or null <email>

Email address (optional)

account_role
string or null
Enum: "account_admin" null

The user's role within the account (null for regular users)

outbound_caller_id_did_id
string or null

ID of the phone number to use as this user's outbound caller ID, overriding the account default. When null, the account default is used.

voicemail_pin
string or null

Numeric PIN for remote voicemail access (4-10 digits). When null, no PIN is set.

object (UserConfig)

User-level configuration settings

object

List of extensions assigned to this user. Only included when expand[]=extensions is requested.

created_at
string <date-time>

Timestamp when it was created

updated_at
string <date-time>

Timestamp when it was last updated

Request samples 

curl -X GET \
  'https://api.dialstack.ai/v1/users/user_01h2xcejqtf2nbrexx3vqjhp42?expand%5B%5D=SOME_ARRAY_VALUE' \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "id": "user_01h2xcejqtf2nbrexx3vqjhp42",
  • "name": "Dr. Alice Smith",
  • "email": "alice@spineline.dev",
  • "created_at": "2025-10-18T10:00:00Z",
  • "updated_at": "2025-10-18T10:00:00Z"
}

Update user

Update user details (name, email, etc.)

Authorizations:
BearerAuthSessionAuth
path Parameters
user_id
required
string
Example: user_01h2xcejqtf2nbrexx3vqjhp42

User identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
name
string or null (EntityName) [ 1 .. 255 ] characters

Display name

email
string <email>

Email address (optional)

outbound_caller_id_did_id
string

ID of the phone number to use as this user's outbound caller ID, overriding the account default. Send null to clear.

voicemail_pin
string or null

Numeric PIN for remote voicemail access (4-10 digits). Send null to clear.

object

User configuration. Only provided fields are updated; omitted fields are left unchanged.

Responses

Response Schema: application/json
id
required
string

Unique identifier

name
string or null [ 1 .. 255 ] characters

Display name

email
string or null <email>

Email address (optional)

account_role
string or null
Enum: "account_admin" null

The user's role within the account (null for regular users)

outbound_caller_id_did_id
string or null

ID of the phone number to use as this user's outbound caller ID, overriding the account default. When null, the account default is used.

voicemail_pin
string or null

Numeric PIN for remote voicemail access (4-10 digits). When null, no PIN is set.

object (UserConfig)

User-level configuration settings

object

List of extensions assigned to this user. Only included when expand[]=extensions is requested.

created_at
string <date-time>

Timestamp when it was created

updated_at
string <date-time>

Timestamp when it was last updated

Request samples

Content type
application/json
{
  • "name": "Spineline",
  • "email": "bob@spineline.dev",
  • "outbound_caller_id_did_id": "string",
  • "voicemail_pin": "1234",
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "id": "user_01h2xcejqtf2nbrexx3vqjhp42",
  • "name": "Dr. Alice Smith",
  • "email": "alice@spineline.dev",
  • "created_at": "2025-10-18T10:00:00Z",
  • "updated_at": "2025-10-18T10:00:00Z"
}

Delete user

Delete a user and all associated endpoints. This operation is irreversible. Active calls will be terminated.

Authorizations:
BearerAuthSessionAuth
path Parameters
user_id
required
string
Example: user_01h2xcejqtf2nbrexx3vqjhp42

User identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Request samples 

curl -X DELETE \
  https://api.dialstack.ai/v1/users/user_01h2xcejqtf2nbrexx3vqjhp42 \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "error": "Invalid request body",
  • "code": "validation_error",
  • "details": { }
}

User Profile

User-scoped REST endpoints for softphone and user-facing applications. Returns data scoped to the authenticated user (own call history, voicemails, presence, device registration). Requires a user token.

Get current user profile

Returns the authenticated user's profile, including their assigned extensions and registered devices.

Authorizations:
UserAuth

Responses

Response Schema: application/json
id
string

User identifier

name
string

User's display name

email
string <email>

User's email address

account_id
string

Account the user belongs to

Array of objects

User's assigned extension dial codes

created_at
string <date-time>
updated_at
string <date-time>

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/me \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "email": "user@example.com",
  • "account_id": "string",
  • "extensions": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List own call history

Returns call records where the authenticated user was a participant. Results are returned in reverse chronological order (newest first).

Authorizations:
UserAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

Number of objects to return. Defaults to 10. Maximum is 100.

direction
string
Enum: "inbound" "outbound"

Filter by call direction

from_date
string <date-time>

Return calls on or after this date (ISO 8601)

to_date
string <date-time>

Return calls before this date (ISO 8601)

Responses

Response Schema: application/json
object
required
string (ListObject)
Value: "list"

String representing the object's type. Always "list" for list responses.

url
required
string (ListUrl)

The URL for accessing this list.

next_page_url
required
string or null (NextPageUrl)

URL to fetch the next page of results. If null, there are no more pages. The URL includes all necessary parameters including the pagination cursor.

previous_page_url
required
string or null (PreviousPageUrl)

URL to fetch the previous page of results. If null, this is the first page. The URL includes all necessary parameters including the pagination cursor.

required
Array of objects (CallLog)

Request samples 

curl -X GET \
  'https://api.dialstack.ai/v1/me/calls?limit=10&direction=SOME_STRING_VALUE&from_date=SOME_STRING_VALUE&to_date=SOME_STRING_VALUE' \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "object": "list",
  • "url": "/v1/accounts",
  • "next_page_url": "/v1/accounts?page=eyJzdGFydGluZ19hZnRlciI6ImFjY3RfMDFoMnhjZWpxdGYybmJyZXh4M3ZxamhwNDEiLCJsaW1pdCI6MTB9",
  • "previous_page_url": "/v1/accounts?page=eyJlbmRpbmdfYmVmb3JlIjoiYWNjdF8wMWgyeGNlanF0ZjJuYnJleHgzdnFqaHA0MSIsImxpbWl0IjoxMH0",
  • "data": [
    ]
}

Get own presence status

Returns the authenticated user's current presence status.

Authorizations:
UserAuth

Responses

Response Schema: application/json
user_id
string

User identifier

status
required
string
Enum: "available" "on_call" "dnd" "away" "offline"

Current presence status:

  • available — user is online and can receive calls
  • on_call — user is currently on an active call
  • dnd — user has enabled Do Not Disturb
  • away — user is away (idle timeout or manual)
  • offline — no active WebRTC or SIP registration
status_text
string or null

Optional custom status message

updated_at
string <date-time>

When the presence status last changed

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/me/presence \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "user_id": "string",
  • "status": "available",
  • "status_text": "string",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update own presence status

Updates the authenticated user's presence status. Only available, dnd, and away can be set manually. The on_call and offline statuses are managed automatically by the system.

Authorizations:
UserAuth
Request Body schema: application/json
required
status
required
string
Enum: "available" "dnd" "away"

Desired presence status (cannot set on_call or offline manually)

status_text
string or null

Optional custom status message (max 100 characters)

Responses

Response Schema: application/json
user_id
string

User identifier

status
required
string
Enum: "available" "on_call" "dnd" "away" "offline"

Current presence status:

  • available — user is online and can receive calls
  • on_call — user is currently on an active call
  • dnd — user has enabled Do Not Disturb
  • away — user is away (idle timeout or manual)
  • offline — no active WebRTC or SIP registration
status_text
string or null

Optional custom status message

updated_at
string <date-time>

When the presence status last changed

Request samples

Content type
application/json
{
  • "status": "available",
  • "status_text": "string"
}

Response samples

Content type
application/json
{
  • "user_id": "string",
  • "status": "available",
  • "status_text": "string",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get emergency address

Returns the authenticated user's registered emergency address for E911. Returns 404 if no address has been registered.

Authorizations:
UserAuth

Responses

Response Schema: application/json
street
required
string

Street address

street2
string or null

Suite, floor, apartment, or room number

city
required
string
state
required
string

Two-letter state/province code

zip
required
string
country
required
string

Two-letter country code (ISO 3166-1 alpha-2)

validated
required
boolean

Whether the address has been validated against the MSAG

updated_at
string <date-time>

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/me/emergency-address \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "street": "123 Main St",
  • "street2": "Suite 400",
  • "city": "San Francisco",
  • "state": "CA",
  • "zip": "94105",
  • "country": "US",
  • "validated": true,
  • "updated_at": "2019-08-24T14:15:22Z"
}

Set emergency address

Registers or updates the user's emergency address for E911. The address is validated against the MSAG (Master Street Address Guide) before saving. If validation fails, the response includes suggestions.

An emergency address is required before the user can place calls. Attempting to dial without a validated address returns an error on the signalling channel.

Authorizations:
UserAuth
Request Body schema: application/json
required
street
required
string

Street address

street2
string or null

Suite, floor, apartment, or room number

city
required
string
state
required
string

Two-letter state/province code

zip
required
string
country
required
string

Two-letter country code (ISO 3166-1 alpha-2)

Responses

Response Schema: application/json
street
required
string

Street address

street2
string or null

Suite, floor, apartment, or room number

city
required
string
state
required
string

Two-letter state/province code

zip
required
string
country
required
string

Two-letter country code (ISO 3166-1 alpha-2)

validated
required
boolean

Whether the address has been validated against the MSAG

updated_at
string <date-time>

Request samples

Content type
application/json
{
  • "street": "string",
  • "street2": "string",
  • "city": "string",
  • "state": "string",
  • "zip": "string",
  • "country": "string"
}

Response samples

Content type
application/json
{
  • "street": "123 Main St",
  • "street2": "Suite 400",
  • "city": "San Francisco",
  • "state": "CA",
  • "zip": "94105",
  • "country": "US",
  • "validated": true,
  • "updated_at": "2019-08-24T14:15:22Z"
}

Extensions

Extension (dial code) management. Extensions map short dial codes to routing targets. Requires account context via DialStack-Account header or session token.

Create an extension

Creates a new extension mapping a dial code to a routing target.

Authorizations:
BearerAuthSessionAuth
header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
number
required
string [ 1 .. 32 ] characters

The extension number (dial code)

target
required
string <= 255 characters

ID of the routing target

Responses

Response Schema: application/json
number
required
string [ 1 .. 32 ] characters

The extension number (dial code)

target
required
string <= 255 characters

ID of the routing target

status
required
string
Enum: "active" "inactive"

Extension status

created_at
required
string <date-time>

When the extension was created

updated_at
required
string <date-time>

When the extension was last modified

Request samples

Content type
application/json
Example
{
  • "number": "105",
  • "target": "user_01h2xcejqtf2nbrexx3vqjhp42"
}

Response samples

Content type
application/json
{
  • "number": "105",
  • "target": "user_01h2xcejqtf2nbrexx3vqjhp42",
  • "status": "active",
  • "created_at": "2025-10-18T10:00:00Z",
  • "updated_at": "2025-10-18T10:00:00Z"
}

List extensions

List all extensions for the account. Optionally filter by target to find extensions pointing to a specific routing target. Results are returned in reverse chronological order (newest first).

Authorizations:
BearerAuthSessionAuth
query Parameters
target
string <= 255 characters
Example: target=user_01h2xcejqtf2nbrexx3vqjhp42

Filter extensions by routing target ID

limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

Number of objects to return. Defaults to 10. Maximum is 100.

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
object
required
string (ListObject)
Value: "list"

String representing the object's type. Always "list" for list responses.

url
required
string (ListUrl)

The URL for accessing this list.

next_page_url
required
string or null (NextPageUrl)

URL to fetch the next page of results. If null, there are no more pages. The URL includes all necessary parameters including the pagination cursor.

previous_page_url
required
string or null (PreviousPageUrl)

URL to fetch the previous page of results. If null, this is the first page. The URL includes all necessary parameters including the pagination cursor.

required
Array of objects (Extension)

Request samples 

curl -X GET \
  'https://api.dialstack.ai/v1/extensions?target=user_01h2xcejqtf2nbrexx3vqjhp42&limit=10' \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "object": "list",
  • "url": "/v1/extensions",
  • "next_page_url": null,
  • "previous_page_url": null,
  • "data": [
    ]
}

Get an extension

Retrieve an extension by its number (dial code).

Authorizations:
BearerAuthSessionAuth
path Parameters
number
required
string
Example: 105

Extension number (dial code)

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
number
required
string [ 1 .. 32 ] characters

The extension number (dial code)

target
required
string <= 255 characters

ID of the routing target

status
required
string
Enum: "active" "inactive"

Extension status

created_at
required
string <date-time>

When the extension was created

updated_at
required
string <date-time>

When the extension was last modified

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/extensions/105 \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "number": "105",
  • "target": "user_01h2xcejqtf2nbrexx3vqjhp42",
  • "status": "active",
  • "created_at": "2025-10-18T10:00:00Z",
  • "updated_at": "2025-10-18T10:00:00Z"
}

Update an extension

Update an existing extension. Only the target can be changed; to change the extension number, delete and recreate the extension.

Authorizations:
BearerAuthSessionAuth
path Parameters
number
required
string
Example: 105

Extension number (dial code)

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
target
string <= 255 characters

ID of the new routing target

Responses

Response Schema: application/json
number
required
string [ 1 .. 32 ] characters

The extension number (dial code)

target
required
string <= 255 characters

ID of the routing target

status
required
string
Enum: "active" "inactive"

Extension status

created_at
required
string <date-time>

When the extension was created

updated_at
required
string <date-time>

When the extension was last modified

Request samples

Content type
application/json
{
  • "target": "user_01h2xcejqtf2nbrexx3vqjhp43"
}

Response samples

Content type
application/json
{
  • "number": "105",
  • "target": "user_01h2xcejqtf2nbrexx3vqjhp42",
  • "status": "active",
  • "created_at": "2025-10-18T10:00:00Z",
  • "updated_at": "2025-10-18T10:00:00Z"
}

Delete an extension

Delete an extension by its number (dial code).

Authorizations:
BearerAuthSessionAuth
path Parameters
number
required
string
Example: 105

Extension number (dial code)

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Request samples 

curl -X DELETE \
  https://api.dialstack.ai/v1/extensions/105 \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "error": "Invalid request body",
  • "code": "validation_error",
  • "details": { }
}

Calls

Call initiation, history, and real-time monitoring. Use POST /v1/calls to initiate click-to-call, GET /v1/calls to retrieve call history, and POST /v1/calls/{call_id}/listeners to stream real-time audio from active calls. Requires account context via DialStack-Account header or session token.

Initiate a call

Initiates an outbound call to a destination by first establishing a connection with the specified user.

Call Flow:

  1. The system rings all of the user's registered devices simultaneously
  2. When the user answers on any device, the system dials the destination
  3. Both legs are bridged together into a single call

The dial_string can be:

  • A phone number in E.164 format (e.g., +15551234567)
  • A local phone number (normalized based on account region)
  • An internal extension
  • An emergency number (e.g., 911)

This is an asynchronous operation. A 202 Accepted response indicates the call request was queued successfully, not that the call has completed or even started.

Authorizations:
BearerAuthSessionAuth
header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
user_id
required
string

The user whose endpoints will ring first. When the user answers, the destination is dialed.

dial_string
required
string

The destination to dial after the user answers. Can be a phone number (E.164 or local format), an extension, or an emergency number.

Responses

Request samples

Content type
application/json
Example
{
  • "user_id": "user_01h2xcejqtf2nbrexx3vqjhp42",
  • "dial_string": "+15551234567"
}

Response samples

Content type
application/json
{
  • "error": "Invalid request body",
  • "code": "validation_error",
  • "details": { }
}

List call logs

List call history for an account with optional filtering. Results are returned in reverse chronological order (newest first).

Authorizations:
BearerAuthSessionAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

Number of objects to return. Defaults to 10. Maximum is 100.

user_id
string

Filter by specific user

endpoint_id
string

Filter by specific endpoint/device

direction
string
Enum: "inbound" "outbound" "internal"

Filter by call direction

from_number
string <= 20 characters

Filter by caller's phone number (exact match)

to_number
string <= 20 characters

Filter by recipient's phone number (exact match)

status
string
Enum: "completed" "no-answer" "busy" "failed" "voicemail"

Filter by call status

from_date
string <date-time>

Return calls started on or after this date (ISO 8601)

to_date
string <date-time>

Return calls started before this date (ISO 8601)

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
object
required
string (ListObject)
Value: "list"

String representing the object's type. Always "list" for list responses.

url
required
string (ListUrl)

The URL for accessing this list.

next_page_url
required
string or null (NextPageUrl)

URL to fetch the next page of results. If null, there are no more pages. The URL includes all necessary parameters including the pagination cursor.

previous_page_url
required
string or null (PreviousPageUrl)

URL to fetch the previous page of results. If null, this is the first page. The URL includes all necessary parameters including the pagination cursor.

required
Array of objects (CallLog)

Request samples 

curl -X GET \
  'https://api.dialstack.ai/v1/calls?limit=10&user_id=SOME_STRING_VALUE&endpoint_id=SOME_STRING_VALUE&direction=SOME_STRING_VALUE&from_number=SOME_STRING_VALUE&to_number=SOME_STRING_VALUE&status=SOME_STRING_VALUE&from_date=SOME_STRING_VALUE&to_date=SOME_STRING_VALUE' \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "object": "list",
  • "url": "/v1/calls",
  • "next_page_url": null,
  • "previous_page_url": null,
  • "data": [
    ]
}

Get call log details

Retrieve a specific call log by ID.

Authorizations:
BearerAuthSessionAuth
path Parameters
call_id
required
string
Example: call_01h2xcejqtf2nbrexx3vqjhp45

Call log identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
id
required
string

Unique identifier

required
EntityId (string) or null

The user associated with this call

required
EntityId (string) or null

The endpoint (device) that handled this call

required
EntityId (string) or null

The DID (phone number) used for this call

direction
required
string
Enum: "inbound" "outbound" "internal"

Call direction (inbound from PSTN, outbound to PSTN, or internal extension-to-extension)

from_number
required
string [ 0 .. 20 ] characters

Caller's phone number or originating extension. May be empty when the originating identity could not be determined.

from_label
required
string or null

Display label for the caller, resolved from the extension's target name (user, dial plan, voice app, or ring group). Null if the number does not match an extension.

to_number
required
string [ 0 .. 20 ] characters

Destination as dialed — an E.164 phone number for PSTN destinations or an internal extension number for routes that terminate inside the account. May be empty when the destination could not be determined.

to_label
required
string or null

Display label for the recipient, resolved from the extension's target name (user, dial plan, voice app, or ring group). Null if the number does not match an extension.

started_at
required
string <date-time>

When the call was initiated

answered_at
required
string or null <date-time>

When the call was answered. Null for unanswered calls.

ended_at
required
string or null <date-time>

When the call ended. Null if the call is still in flight.

duration_seconds
required
integer or null >= 0

Call duration in seconds (from answer to hangup). Null for unanswered calls.

status
required
string
Enum: "completed" "no-answer" "busy" "failed" "voicemail"

Final call status

summary
required
string or null

AI-generated summary of the call. Null if call wasn't recorded or transcript not yet processed.

recording_url
required
string or null <uri>

Signed URL to download the call recording audio. Null if the call was not recorded. The URL expires after 10 minutes.

required
Array of objects (QualityMetricLeg)

RTP quality metrics per call leg. Each call may have multiple legs (e.g., PSTN + endpoint for inbound calls). Empty array for unanswered calls.

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/calls/call_01h2xcejqtf2nbrexx3vqjhp45 \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
Example
{
  • "id": "call_01h2xcejqtf2nbrexx3vqjhp45",
  • "user_id": "user_01h2xcejqtf2nbrexx3vqjhp42",
  • "endpoint_id": "ep_01h2xcejqtf2nbrexx3vqjhp43",
  • "did_id": "did_01h2xcejqtf2nbrexx3vqjhp46",
  • "direction": "inbound",
  • "from_number": "+14155551234",
  • "to_number": "+14155559876",
  • "started_at": "2025-10-18T14:30:00Z",
  • "answered_at": "2025-10-18T14:30:05Z",
  • "ended_at": "2025-10-18T14:35:30Z",
  • "duration_seconds": 325,
  • "status": "completed"
}

Control an active call

Send actions to control an active call. This is the central API for all call control operations such as attaching audio streams or transferring calls.

Actions are processed sequentially. Each action may block processing or allow it to continue based on its outcome (see action descriptions for details).

Replacing actions: If the call is currently executing actions and you send a new update, the previous action list is completely replaced. Processing of the current action is interrupted immediately, and processing resumes with the first action in the new list.

Example - Attach AI voice and fallback to human:

{
  "actions": [
    {"type": "attach", "url": "wss://ai.example.com/voice"},
    {"type": "transfer", "extension": "100"}
  ]
}

In this example, the AI handles the call via WebSocket. When the WebSocket disconnects, the call transfers to extension 100.

Authorizations:
BearerAuthSessionAuth
path Parameters
call_id
required
string
Example: call_01h2xcejqtf2nbrexx3vqjhp45

Call log identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
required
Array of objects (CallAction) non-empty

List of actions to execute on the call. Actions are processed sequentially. Each action may block processing or allow it to continue based on its outcome.

Supported Actions:

attach

Connect bidirectional audio streaming to a WebSocket URL.

  • type: "attach"
  • url: WebSocket URL (wss://) for bidirectional audio streaming

Processing behavior: This action blocks processing while the WebSocket connection is active. When the WebSocket disconnects (either side closes), processing resumes with the next action.

See WebSocket API for the message protocol.

transfer

Blind transfer the call to an extension number.

  • type: "transfer"
  • extension: Extension number to transfer to

Processing behavior: If the transfer target answers or the caller hangs up, processing stops. If the transfer cannot be completed (no answer, busy, rejected), processing continues with the next action.

Array (non-empty)
type
required
string

Action type

url
required
string <uri>

WebSocket URL (wss://) for bidirectional audio streaming

object

Optional key/value pairs echoed on the media WebSocket begin message. Useful for correlating the stream with application-side state (agent ID, queue, trace ID, etc.) without a separate lookup.

Responses

Request samples

Content type
application/json
Example
{
  • "actions": [
    ]
}

Response samples

Content type
application/json
{
  • "error": "Invalid request body",
  • "code": "validation_error",
  • "details": { }
}

Get call transcript

Retrieve the transcript for a specific call.

Transcription Status:

  • pending: The call has been recorded but transcription has not started
  • processing: Transcription is currently in progress
  • completed: Transcription is complete and text is available
  • failed: Transcription failed (text will be null)

Note: Returns 404 if the call exists but has no recording, or if the call does not exist. Not all calls have recordings (depends on account configuration).

Authorizations:
BearerAuthSessionAuth
path Parameters
call_id
required
string
Example: call_01h2xcejqtf2nbrexx3vqjhp45

Call log identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
call_id
required
string

Unique identifier

status
required
string
Enum: "pending" "processing" "completed" "failed"

Current status of the transcription:

  • pending: Recording uploaded, transcription not started
  • processing: Transcription in progress
  • completed: Transcription finished successfully
  • failed: Transcription failed
text
string or null

Full text transcript. Null if transcription is not completed.

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/calls/call_01h2xcejqtf2nbrexx3vqjhp45/transcript \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
Example
{
  • "call_id": "call_01h2xcejqtf2nbrexx3vqjhp45",
  • "status": "completed",
  • "text": "Hello, this is Dr. Smith calling..."
}

Get call recording

Retrieve the recording for a specific call. Returns metadata and a signed download URL.

The download URL is valid for 10 minutes. After expiration, request a new URL by calling this endpoint again.

Note: Returns 404 if the call exists but has no recording, or if the call does not exist. Not all calls have recordings (depends on account configuration).

Authorizations:
BearerAuthSessionAuth
path Parameters
call_id
required
string
Example: call_01h2xcejqtf2nbrexx3vqjhp45

Call log identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
call_id
required
string

Unique identifier

duration_seconds
integer or null >= 0

Duration of the recording in seconds. Null if not available.

file_size_bytes
integer or null >= 0

Size of the recording file in bytes. Null if not available.

download_url
required
string <uri>

Signed URL to download the recording audio file. Expires after 10 minutes.

expires_at
required
string <date-time>

When the download URL expires

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/calls/call_01h2xcejqtf2nbrexx3vqjhp45/recording \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{}

Create a listener

Start streaming real-time audio from an active call to a WebSocket URL.

DialStack opens an outbound WebSocket connection to the specified URL and streams audio unidirectionally (DialStack to your server). The call is not affected — both parties remain unaware of the listener.

Use the channel parameter to select which audio to receive:

  • caller — audio from the party that initiated the call
  • callee — audio from the party that received the call
  • both — both channels, delivered as separate tagged messages

The listener automatically stops when the call ends. You can also stop it explicitly with DELETE /v1/calls/{call_id}/listeners/{listener_id}.

Returns 409 Conflict if the call is not in a state that supports listeners (e.g., still ringing or already ended). Retry after the call is answered.

See the WebSocket API for the listener message protocol.

Authorizations:
BearerAuthSessionAuth
path Parameters
call_id
required
string
Example: call_01h2xcejqtf2nbrexx3vqjhp45

Call log identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
url
required
string <uri>

Secure WebSocket URL where DialStack will stream audio. Must use the wss:// scheme; insecure ws:// URLs are rejected with 422.

channel
string
Default: "both"
Enum: "caller" "callee" "both"

Which audio channel(s) to stream:

  • caller: audio from the party that initiated the call
  • callee: audio from the party that received the call
  • both: both channels, delivered as separate tagged messages

Responses

Response Schema: application/json
id
required
string

Unique identifier

call_id
required
string

The active call being listened to

url
required
string <uri>

WebSocket URL where audio is being streamed

channel
required
string
Enum: "caller" "callee" "both"

Which audio channel(s) to stream:

  • caller: audio from the party that initiated the call
  • callee: audio from the party that received the call
  • both: both channels, delivered as separate tagged messages
created_at
required
string <date-time>

Timestamp when it was created

Request samples

Content type
application/json
Example
{
  • "url": "wss://your-server.example.com/audio",
  • "channel": "both"
}

Response samples

Content type
application/json
{
  • "id": "lstn_01h2xcejqtf2nbrexx3vqjhp50",
  • "call_id": "call_01h2xcejqtf2nbrexx3vqjhp45",
  • "url": "wss://your-server.example.com/audio",
  • "channel": "both",
  • "created_at": "2026-04-02T14:30:00Z"
}

List listeners

List the listeners currently attached to a call. Listeners exist only for the duration of the call — once the call ends they no longer exist, and this endpoint returns an empty list. Call IDs that don't belong to the caller's account return 404.

Authorizations:
BearerAuthSessionAuth
path Parameters
call_id
required
string
Example: call_01h2xcejqtf2nbrexx3vqjhp45

Call log identifier

query Parameters
limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

Number of objects to return. Defaults to 10. Maximum is 100.

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
object
required
string (ListObject)
Value: "list"

String representing the object's type. Always "list" for list responses.

url
required
string (ListUrl)

The URL for accessing this list.

next_page_url
required
string or null (NextPageUrl)

URL to fetch the next page of results. If null, there are no more pages. The URL includes all necessary parameters including the pagination cursor.

previous_page_url
required
string or null (PreviousPageUrl)

URL to fetch the previous page of results. If null, this is the first page. The URL includes all necessary parameters including the pagination cursor.

required
Array of objects (Listener)

Request samples 

curl -X GET \
  'https://api.dialstack.ai/v1/calls/call_01h2xcejqtf2nbrexx3vqjhp45/listeners?limit=10' \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "object": "list",
  • "url": "/v1/accounts",
  • "next_page_url": "/v1/accounts?page=eyJzdGFydGluZ19hZnRlciI6ImFjY3RfMDFoMnhjZWpxdGYybmJyZXh4M3ZxamhwNDEiLCJsaW1pdCI6MTB9",
  • "previous_page_url": "/v1/accounts?page=eyJlbmRpbmdfYmVmb3JlIjoiYWNjdF8wMWgyeGNlanF0ZjJuYnJleHgzdnFqaHA0MSIsImxpbWl0IjoxMH0",
  • "data": [
    ]
}

Get listener

Retrieve a listener. Listeners exist only for the duration of the call; once the call ends the listener no longer exists and this endpoint returns 404.

Authorizations:
BearerAuthSessionAuth
path Parameters
call_id
required
string
Example: call_01h2xcejqtf2nbrexx3vqjhp45

Call log identifier

listener_id
required
string
Example: lstn_01h2xcejqtf2nbrexx3vqjhp50

Listener identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
id
required
string

Unique identifier

call_id
required
string

The active call being listened to

url
required
string <uri>

WebSocket URL where audio is being streamed

channel
required
string
Enum: "caller" "callee" "both"

Which audio channel(s) to stream:

  • caller: audio from the party that initiated the call
  • callee: audio from the party that received the call
  • both: both channels, delivered as separate tagged messages
created_at
required
string <date-time>

Timestamp when it was created

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/calls/call_01h2xcejqtf2nbrexx3vqjhp45/listeners/lstn_01h2xcejqtf2nbrexx3vqjhp50 \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "id": "lstn_01h2xcejqtf2nbrexx3vqjhp50",
  • "call_id": "call_01h2xcejqtf2nbrexx3vqjhp45",
  • "url": "wss://your-server.example.com/audio",
  • "channel": "both",
  • "created_at": "2025-10-17T14:30:00Z"
}

Stop a listener

Stop streaming audio and close the WebSocket connection for this listener. The call is not affected. Listeners exist only for the duration of the call, so once the call has ended this endpoint returns 404.

Authorizations:
BearerAuthSessionAuth
path Parameters
call_id
required
string
Example: call_01h2xcejqtf2nbrexx3vqjhp45

Call log identifier

listener_id
required
string
Example: lstn_01h2xcejqtf2nbrexx3vqjhp50

Listener identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Request samples 

curl -X DELETE \
  https://api.dialstack.ai/v1/calls/call_01h2xcejqtf2nbrexx3vqjhp45/listeners/lstn_01h2xcejqtf2nbrexx3vqjhp50 \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "error": "Invalid request body",
  • "code": "validation_error",
  • "details": { }
}

Voicemails

Voicemail message management. Requires account context via DialStack-Account header or session token.

List voicemails

List voicemails visible to the authenticated account, across both per-user mailboxes and shared voicemail boxes.

Results are returned in reverse chronological order (newest first). Use owner (a user ID or shared voicemail box ID) to scope results to a single owner.

Authorizations:
BearerAuthSessionAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

Number of objects to return. Defaults to 10. Maximum is 100.

owner
string

Filter to voicemails belonging to a specific owner (a user ID or a shared voicemail box ID).

is_read
boolean

Filter by read status.

from_date
string <date-time>

Return voicemails created on or after this date (ISO 8601).

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
object
required
string (ListObject)
Value: "list"

String representing the object's type. Always "list" for list responses.

url
required
string (ListUrl)

The URL for accessing this list.

next_page_url
required
string or null (NextPageUrl)

URL to fetch the next page of results. If null, there are no more pages. The URL includes all necessary parameters including the pagination cursor.

previous_page_url
required
string or null (PreviousPageUrl)

URL to fetch the previous page of results. If null, this is the first page. The URL includes all necessary parameters including the pagination cursor.

required
Array of objects (Voicemail)

Request samples 

curl -X GET \
  'https://api.dialstack.ai/v1/voicemails?limit=10&owner=SOME_STRING_VALUE&is_read=SOME_BOOLEAN_VALUE&from_date=SOME_STRING_VALUE' \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "object": "list",
  • "url": "/v1/accounts",
  • "next_page_url": "/v1/accounts?page=eyJzdGFydGluZ19hZnRlciI6ImFjY3RfMDFoMnhjZWpxdGYybmJyZXh4M3ZxamhwNDEiLCJsaW1pdCI6MTB9",
  • "previous_page_url": "/v1/accounts?page=eyJlbmRpbmdfYmVmb3JlIjoiYWNjdF8wMWgyeGNlanF0ZjJuYnJleHgzdnFqaHA0MSIsImxpbWl0IjoxMH0",
  • "data": []
}

Get a voicemail

Retrieve a specific voicemail by ID, including the audio_url for playback. Voicemail IDs are globally unique, so no owner context is required in the URL.

Authorizations:
BearerAuthSessionAuth
path Parameters
voicemail_id
required
string
Example: vm_01h2xcejqtf2nbrexx3vqjhp44

Voicemail identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
id
required
string

Unique identifier

owner
required
string

Unique identifier

from_number
required
string <= 20 characters

Caller's phone number

from_name
string or null <= 255 characters

Caller's name (if available from caller ID)

duration_seconds
required
integer >= 0

Length of the voicemail recording in seconds

format
required
string <= 10 characters

Audio format

audio_url
required
string <uri>

URL for downloading the audio recording

is_read
required
boolean

Whether the voicemail has been listened to

created_at
required
string <date-time>

Timestamp when it was created

read_at
string or null <date-time>

When the voicemail was marked as read

summary
string or null

AI-generated summary of the voicemail content. Null if transcription not yet processed.

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/voicemails/vm_01h2xcejqtf2nbrexx3vqjhp44 \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{}

Update a voicemail

Update voicemail status (mark as read/unread).

Authorizations:
BearerAuthSessionAuth
path Parameters
voicemail_id
required
string
Example: vm_01h2xcejqtf2nbrexx3vqjhp44

Voicemail identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
is_read
boolean

Mark voicemail as read or unread

Responses

Response Schema: application/json
id
required
string

Unique identifier

owner
required
string

Unique identifier

from_number
required
string <= 20 characters

Caller's phone number

from_name
string or null <= 255 characters

Caller's name (if available from caller ID)

duration_seconds
required
integer >= 0

Length of the voicemail recording in seconds

format
required
string <= 10 characters

Audio format

audio_url
required
string <uri>

URL for downloading the audio recording

is_read
required
boolean

Whether the voicemail has been listened to

created_at
required
string <date-time>

Timestamp when it was created

read_at
string or null <date-time>

When the voicemail was marked as read

summary
string or null

AI-generated summary of the voicemail content. Null if transcription not yet processed.

Request samples

Content type
application/json
Example
{
  • "is_read": true
}

Response samples

Content type
application/json
{}

Delete a voicemail

Permanently delete a voicemail and its audio recording. This operation is irreversible.

Authorizations:
BearerAuthSessionAuth
path Parameters
voicemail_id
required
string
Example: vm_01h2xcejqtf2nbrexx3vqjhp44

Voicemail identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Request samples 

curl -X DELETE \
  https://api.dialstack.ai/v1/voicemails/vm_01h2xcejqtf2nbrexx3vqjhp44 \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "error": "Invalid request body",
  • "code": "validation_error",
  • "details": { }
}

Get a voicemail transcript

Retrieve the transcript for a specific voicemail.

Transcription Status:

  • pending: The voicemail has been saved but transcription has not started
  • processing: Transcription is currently in progress
  • completed: Transcription is complete and text is available
  • failed: Transcription failed (text will be null)

Voicemails are automatically transcribed after being saved.

Authorizations:
BearerAuthSessionAuth
path Parameters
voicemail_id
required
string
Example: vm_01h2xcejqtf2nbrexx3vqjhp44

Voicemail identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
voicemail_id
required
string

Unique identifier

status
required
string
Enum: "pending" "processing" "completed" "failed"

Current status of the transcription:

  • pending: Voicemail uploaded, transcription not started
  • processing: Transcription in progress
  • completed: Transcription finished successfully
  • failed: Transcription failed
text
string or null

Full text transcript. Null if transcription is not completed.

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/voicemails/vm_01h2xcejqtf2nbrexx3vqjhp44/transcript \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
Example
{
  • "voicemail_id": "vm_01h2xcejqtf2nbrexx3vqjhp45",
  • "status": "completed",
  • "text": "Hi, this is John Smith calling about my appointment tomorrow..."
}

Upload a voicemail greeting

Uploads (or replaces) a custom greeting for a user mailbox or a shared voicemail box.

Accepts a multipart form with a file field containing the audio. The audio is validated and transcoded server-side to the storage format (mono µ-law 8 kHz WAV).

  • Maximum file size: 5 MB.
  • Maximum duration: 90 seconds.
  • Supported input formats: WAV (PCM s16 / µ-law / A-law), MP3, AAC, Ogg Vorbis, Opus.

Re-uploading for the same (owner, type) overwrites the existing greeting.

Authorizations:
BearerAuthSessionAuth
path Parameters
owner
required
string

ID of the mailbox owner — either a user or a shared voicemail box.

type
required
string
Value: "unavailable"

The greeting variant to operate on. Today only unavailable is supported.

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: multipart/form-data
required
file
required
string <binary>

Audio file to upload.

Responses

Response Schema: application/json
owner
required
string

Unique identifier

greeting_type
required
string
Value: "unavailable"

The greeting variant. Today only unavailable is supported — the full custom greeting that replaces the system prompts (caller hears it when the owner does not answer).

format
required
string
Value: "wav"

Audio format of the stored greeting.

duration_seconds
required
number <float> >= 0

Length of the greeting audio in seconds.

size_bytes
required
integer <int64> >= 0

Size of the stored greeting audio in bytes (post-transcode).

url
required
string <uri>

Short-lived signed URL (5 minutes) for downloading the greeting audio.

updated_at
required
string <date-time>

When the greeting was last uploaded or replaced.

Request samples 

curl -X POST \
  https://api.dialstack.ai/v1/voicemail_greetings/%7Bowner%7D/%7Btype%7D \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41' \
  -H 'content-type: multipart/form-data' \
  --form file=string

Response samples

Content type
application/json
{
  • "owner": "string",
  • "greeting_type": "unavailable",
  • "format": "wav",
  • "duration_seconds": 12.4,
  • "size_bytes": 98560,
  • "url": "http://example.com",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get a voicemail greeting

Returns the current custom greeting for a mailbox owner, including a short-lived signed URL for audio playback.

Authorizations:
BearerAuthSessionAuth
path Parameters
owner
required
string

ID of the mailbox owner — either a user or a shared voicemail box.

type
required
string
Value: "unavailable"

The greeting variant to operate on. Today only unavailable is supported.

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
owner
required
string

Unique identifier

greeting_type
required
string
Value: "unavailable"

The greeting variant. Today only unavailable is supported — the full custom greeting that replaces the system prompts (caller hears it when the owner does not answer).

format
required
string
Value: "wav"

Audio format of the stored greeting.

duration_seconds
required
number <float> >= 0

Length of the greeting audio in seconds.

size_bytes
required
integer <int64> >= 0

Size of the stored greeting audio in bytes (post-transcode).

url
required
string <uri>

Short-lived signed URL (5 minutes) for downloading the greeting audio.

updated_at
required
string <date-time>

When the greeting was last uploaded or replaced.

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/voicemail_greetings/%7Bowner%7D/%7Btype%7D \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "owner": "string",
  • "greeting_type": "unavailable",
  • "format": "wav",
  • "duration_seconds": 12.4,
  • "size_bytes": 98560,
  • "url": "http://example.com",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a voicemail greeting

Removes the custom greeting for a mailbox owner. The mailbox reverts to the system-default prompts.

This operation is idempotent — returns 204 No Content whether or not a greeting was previously set.

Authorizations:
BearerAuthSessionAuth
path Parameters
owner
required
string

ID of the mailbox owner — either a user or a shared voicemail box.

type
required
string
Value: "unavailable"

The greeting variant to operate on. Today only unavailable is supported.

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Request samples 

curl -X DELETE \
  https://api.dialstack.ai/v1/voicemail_greetings/%7Bowner%7D/%7Btype%7D \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "error": "Invalid request body",
  • "code": "validation_error",
  • "details": { }
}

Events

Real-time event streaming via Server-Sent Events (SSE). Use this endpoint to receive live notifications about calls, voicemails, and other account activity. Requires account context via DialStack-Account header or session token.

Stream real-time events

Establish a Server-Sent Events (SSE) connection to receive real-time notifications about account activity such as incoming calls.

Connection Behavior:

  • On successful connection, a connected event is sent immediately
  • Events are streamed in real-time as they occur
  • The connection stays open indefinitely until the client disconnects
  • Clients should implement automatic reconnection with exponential backoff

Event Format: Events follow the SSE specification with event: and data: fields:

event: call.incoming
data: {"event":"call.incoming","account_id":"acct_...","from_number":"+14155551234","to_number":"+14155559876"}

Available Event Types:

connected

Sent immediately when the SSE connection is established.

{"message": "Connected to event stream"}

call.incoming

Sent when an incoming call arrives for the account.

Field Type Description
event string Always "call.incoming"
account_id string Account receiving the call
call_id string Call detail record identifier
from_number string Caller's phone number (E.164)
from_name string | null Caller's name from caller ID
to_number string Called phone number (E.164)
from_user_id string | null User who initiated the call, when known
to_user_id string | null User the call is destined for, when known

call.initiated

Sent when an outbound call starts dialing.

Field Type Description
event string Always "call.initiated"
account_id string Account initiating the call
call_id string Call detail record identifier
from_number string Outbound caller number (E.164)
to_number string Destination number (E.164)
user_id string User who initiated the call (alias for from_user_id)
from_user_id string | null User who initiated the call, when known
to_user_id string | null User the call is destined for, when known

call.ringing

Sent once per (call, user) when the platform is about to ring a user's phone(s). Fires regardless of how the call was routed to the user — direct extension, ring group, ring-all-users, Find-Me/Follow-Me (including forwarding to an external number), dial plan Dial User node, voice app transfer, or a parked-call ring-back. The event indicates logical "we're ringing this user", not a SIP 180 Ringing signal.

A user with multiple endpoints (desk phone + mobile app) produces one event, not one per device.

No stop event is emitted — consumers that dismiss UI on ring stop (e.g. screen pop) should rely on call.answered or call.end.

Field Type Description
event string Always "call.ringing"
account_id string Account owning the user being rung
call_id string Call detail record identifier
user_id string User whose phone(s) are being rung
from_number string Caller's phone number (E.164)
from_name string | null Caller's name from caller ID
to_number string Called phone number (E.164)
ringing_at string ISO 8601 timestamp

call.answered

Sent when a call is answered.

Field Type Description
event string Always "call.answered"
account_id string Account where the call was answered
call_id string Call detail record identifier
from_number string Caller's phone number (E.164)
to_number string Called phone number (E.164)
direction string "inbound" or "outbound"
answered_at string ISO 8601 timestamp
from_user_id string | null User who initiated the call, when known
to_user_id string | null User who answered, when applicable

call.end

Sent when a call ends.

Field Type Description
event string Always "call.end"
account_id string Account where the call ended
call_id string Call detail record identifier
from_number string Caller's phone number (E.164)
to_number string Called phone number (E.164)
direction string "inbound" or "outbound"
status string "completed", "no-answer", "busy", "failed", or "voicemail"
duration_seconds integer Call duration in seconds
ended_at string ISO 8601 timestamp
from_user_id string | null User who initiated the call, when known
to_user_id string | null User the call reached, when applicable

call.transfer

Sent when a call is transferred.

Field Type Description
event string Always "call.transfer"
account_id string Account where the transfer occurred
call_id string Call detail record identifier
from_number string Caller's phone number (E.164)
to_number string Original called number (E.164)
transferred_to string Transfer target (extension number)
Authorizations:
BearerAuthSessionAuth
header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Headers
Content-Type
string
Example: "text/event-stream"
Cache-Control
string
Example: "no-cache"
Connection
string
Example: "keep-alive"
Response Schema: text/event-stream
string

Server-Sent Events stream. Each event has an event: type and data: payload.

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/events \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
text/event-stream
Example
event: connected
data: {"message":"Connected to event stream"}

WebRTC

WebRTC configuration for softphone applications. Provides ICE server credentials for establishing peer connections. The signalling protocol is documented in the WebRTC Signalling Protocol. Requires a user token.

Get ICE server credentials

Returns STUN and TURN server configurations for establishing WebRTC peer connections. TURN credentials are time-limited — fetch fresh credentials before the expires_at timestamp.

Call this before initiating or answering a call. The returned configuration can be passed directly to RTCPeerConnection as iceServers.

Authorizations:
UserAuth

Responses

Response Schema: application/json
required
Array of objects (IceServer)

List of ICE server configurations for WebRTC peer connections

expires_at
required
string <date-time>

When the TURN credentials expire. Fetch new credentials before this time.

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/webrtc/ice-servers \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "ice_servers": [
    ],
  • "expires_at": "2026-04-10T22:00:00Z"
}

Dial Plans

Visual call routing graph management. Dial plans define how calls are routed through nodes (schedules, extensions). Multiple extensions can share the same dial plan. Requires account context via DialStack-Account header or session token.

Create a dial plan

Create a new visual call routing graph for the account. See the DialPlanNode schema for the full list of node types and their configuration options.

Authorizations:
BearerAuthSessionAuth
header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
name
required
string [ 1 .. 255 ] characters

Display name for the dial plan

entry_node
string

ID of the first node to execute (optional for draft dial plans)

Array of objects (DialPlanNode)

All nodes in the dial plan graph

Responses

Response Schema: application/json
id
required
string

Unique identifier for the dial plan

name
required
string

Display name for the dial plan

entry_node
required
string

ID of the first node to execute (the implicit Start node connects here)

required
Array of objects (DialPlanNode)

All nodes in the dial plan graph

created_at
required
string <date-time>

When the dial plan was created

updated_at
required
string <date-time>

When the dial plan was last modified

object

List of extensions assigned to this dial plan. Only included when expand[]=extensions is requested.

Request samples

Content type
application/json
{
  • "name": "Main Line Routing",
  • "entry_node": "check_hours",
  • "nodes": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "dp_01h2xcejqtf2nbrexx3vqjhp60",
  • "name": "Main Line Routing",
  • "entry_node": "check_hours",
  • "nodes": [
    ],
  • "created_at": "2025-10-18T10:00:00Z",
  • "updated_at": "2025-10-18T10:00:00Z"
}

List dial plans

List all dial plans for the account. Results are returned in reverse chronological order (newest first).

Authorizations:
BearerAuthSessionAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

Number of objects to return. Defaults to 10. Maximum is 100.

expand[]
Array of strings
Items Value: "extensions"

Related resources to include inline. Supported values: extensions.

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
object
required
string (ListObject)
Value: "list"

String representing the object's type. Always "list" for list responses.

url
required
string (ListUrl)

The URL for accessing this list.

next_page_url
required
string or null (NextPageUrl)

URL to fetch the next page of results. If null, there are no more pages. The URL includes all necessary parameters including the pagination cursor.

previous_page_url
required
string or null (PreviousPageUrl)

URL to fetch the previous page of results. If null, this is the first page. The URL includes all necessary parameters including the pagination cursor.

required
Array of objects (DialPlan)

Request samples 

curl -X GET \
  'https://api.dialstack.ai/v1/dialplans?limit=10&expand%5B%5D=SOME_ARRAY_VALUE' \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "object": "list",
  • "url": "/v1/accounts",
  • "next_page_url": "/v1/accounts?page=eyJzdGFydGluZ19hZnRlciI6ImFjY3RfMDFoMnhjZWpxdGYybmJyZXh4M3ZxamhwNDEiLCJsaW1pdCI6MTB9",
  • "previous_page_url": "/v1/accounts?page=eyJlbmRpbmdfYmVmb3JlIjoiYWNjdF8wMWgyeGNlanF0ZjJuYnJleHgzdnFqaHA0MSIsImxpbWl0IjoxMH0",
  • "data": [
    ]
}

Get a dial plan

Retrieve a dial plan by ID.

Authorizations:
BearerAuthSessionAuth
path Parameters
dial_plan_id
required
string
Example: dp_01h2xcejqtf2nbrexx3vqjhp60

The dial plan identifier

query Parameters
expand[]
Array of strings
Items Value: "extensions"

Related resources to include inline. Supported values: extensions.

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
id
required
string

Unique identifier for the dial plan

name
required
string

Display name for the dial plan

entry_node
required
string

ID of the first node to execute (the implicit Start node connects here)

required
Array of objects (DialPlanNode)

All nodes in the dial plan graph

created_at
required
string <date-time>

When the dial plan was created

updated_at
required
string <date-time>

When the dial plan was last modified

object

List of extensions assigned to this dial plan. Only included when expand[]=extensions is requested.

Request samples 

curl -X GET \
  'https://api.dialstack.ai/v1/dialplans/dp_01h2xcejqtf2nbrexx3vqjhp60?expand%5B%5D=SOME_ARRAY_VALUE' \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "id": "dp_01h2xcejqtf2nbrexx3vqjhp60",
  • "name": "Main Line Routing",
  • "entry_node": "check_hours",
  • "nodes": [
    ],
  • "created_at": "2025-10-18T10:00:00Z",
  • "updated_at": "2025-10-18T10:00:00Z",
  • "extensions": {
    }
}

Update a dial plan

Update an existing dial plan. All fields are optional; only provided fields will be updated.

When nodes is provided, it fully replaces all nodes (not a partial node update).

Authorizations:
BearerAuthSessionAuth
path Parameters
dial_plan_id
required
string
Example: dp_01h2xcejqtf2nbrexx3vqjhp60

The dial plan identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
name
string [ 1 .. 255 ] characters

Display name for the dial plan

entry_node
string

ID of the first node to execute

Array of objects (DialPlanNode)

All nodes in the dial plan graph (full replacement)

Responses

Response Schema: application/json
id
required
string

Unique identifier for the dial plan

name
required
string

Display name for the dial plan

entry_node
required
string

ID of the first node to execute (the implicit Start node connects here)

required
Array of objects (DialPlanNode)

All nodes in the dial plan graph

created_at
required
string <date-time>

When the dial plan was created

updated_at
required
string <date-time>

When the dial plan was last modified

object

List of extensions assigned to this dial plan. Only included when expand[]=extensions is requested.

Request samples

Content type
application/json
Example
{
  • "name": "Updated Main Line Routing"
}

Response samples

Content type
application/json
{
  • "id": "dp_01h2xcejqtf2nbrexx3vqjhp60",
  • "name": "Main Line Routing",
  • "entry_node": "check_hours",
  • "nodes": [
    ],
  • "created_at": "2025-10-18T10:00:00Z",
  • "updated_at": "2025-10-18T10:00:00Z",
  • "extensions": {
    }
}

Delete a dial plan

Delete a dial plan by ID.

Note: Deletion will fail if any extensions still reference this dial plan. You must first update or delete those extensions.

Authorizations:
BearerAuthSessionAuth
path Parameters
dial_plan_id
required
string
Example: dp_01h2xcejqtf2nbrexx3vqjhp60

The dial plan identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Request samples 

curl -X DELETE \
  https://api.dialstack.ai/v1/dialplans/dp_01h2xcejqtf2nbrexx3vqjhp60 \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "error": "Invalid request body",
  • "code": "validation_error",
  • "details": { }
}

Ring Groups

Ring group management for parallel dialing (call forking). Ring groups dial multiple members simultaneously; the first to answer wins. Requires account context via DialStack-Account header or session token.

Create a ring group

Creates a new ring group for parallel dialing.

When a call is routed to a ring group, all members ring simultaneously. The first member to answer wins; other ringing channels are cancelled.

Authorizations:
BearerAuthSessionAuth
header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
name
required
string [ 1 .. 255 ] characters

Display name for the ring group

timeout_seconds
integer [ 5 .. 300 ]

How long to ring members (defaults to 20)

ignore_forwarding
boolean

Ignore SIP 302 redirects from devices

confirm_external
boolean

Require external (phone number) members to press a key before being connected

timeout_action
string
Enum: "ring_user" "voicemail" "queue"

Action to take when the ring group times out:

  • ring_user — ring the fallback user.
  • voicemail — send to voicemail (the user's box or a shared box, determined by timeout_target).
  • queue — overflow the caller into a queue.
timeout_target
string

ID of the timeout target — a user, shared voicemail box, or queue, paired with timeout_action. Required when timeout_action is set.

Responses

Response Schema: application/json
id
required
string

Unique identifier

name
required
string

Display name

timeout_seconds
required
integer [ 5 .. 300 ]

How long to ring members before giving up (seconds)

ignore_forwarding
required
boolean

When true, ignores SIP 302 redirects (call forwarding) from devices

confirm_external
required
boolean

When true, requires external (phone number) members to press a key before being connected

timeout_action
string or null
Enum: "ring_user" "voicemail" "queue" null

Action to take when the ring group times out:

  • ring_user — ring the fallback user.
  • voicemail — send to voicemail (the user's box or a shared box, determined by timeout_target).
  • queue — overflow the caller into a queue.
timeout_target
string or null

ID of the timeout target — a user, shared voicemail box, or queue, paired with timeout_action. Required when timeout_action is set.

object

List of extensions assigned to this ring group. Only included when expand[]=extensions is requested.

required
Array of objects (RingGroupMember)

List of members in this ring group

created_at
required
string <date-time> (CreatedAt)

Timestamp when it was created

updated_at
required
string <date-time> (UpdatedAt)

Timestamp when it was last updated

Request samples

Content type
application/json
{
  • "name": "Sales Team",
  • "timeout_seconds": 30,
  • "ignore_forwarding": false,
  • "confirm_external": false,
  • "timeout_action": "voicemail",
  • "timeout_target": "user_01h2xcejqtf2nbrexx3vqjhp42"
}

Response samples

Content type
application/json
{
  • "id": "rg_01h2xcejqtf2nbrexx3vqjhp51",
  • "name": "Sales Team",
  • "timeout_seconds": 30,
  • "ignore_forwarding": false,
  • "confirm_external": false,
  • "timeout_action": "voicemail",
  • "timeout_target": "user_01h2xcejqtf2nbrexx3vqjhp42",
  • "extensions": {
    },
  • "members": [
    ],
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

List ring groups

Returns a paginated list of ring groups for the account.

Authorizations:
BearerAuthSessionAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

Number of objects to return. Defaults to 10. Maximum is 100.

expand[]
Array of strings
Items Value: "extensions"

Related resources to include inline. Supported values: extensions.

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
object
string (ListObject)
Value: "list"

String representing the object's type. Always "list" for list responses.

url
string (ListUrl)

The URL for accessing this list.

next_page_url
string or null (NextPageUrl)

URL to fetch the next page of results. If null, there are no more pages. The URL includes all necessary parameters including the pagination cursor.

previous_page_url
string or null (PreviousPageUrl)

URL to fetch the previous page of results. If null, this is the first page. The URL includes all necessary parameters including the pagination cursor.

Array of objects (RingGroup)

Request samples 

curl -X GET \
  'https://api.dialstack.ai/v1/ring_groups?limit=10&expand%5B%5D=SOME_ARRAY_VALUE' \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "object": "list",
  • "url": "/v1/accounts",
  • "next_page_url": "/v1/accounts?page=eyJzdGFydGluZ19hZnRlciI6ImFjY3RfMDFoMnhjZWpxdGYybmJyZXh4M3ZxamhwNDEiLCJsaW1pdCI6MTB9",
  • "previous_page_url": "/v1/accounts?page=eyJlbmRpbmdfYmVmb3JlIjoiYWNjdF8wMWgyeGNlanF0ZjJuYnJleHgzdnFqaHA0MSIsImxpbWl0IjoxMH0",
  • "data": [
    ]
}

Get a ring group

Retrieves a ring group by ID, including its members.

Authorizations:
BearerAuthSessionAuth
path Parameters
ring_group_id
required
string
Example: rg_01h2xcejqtf2nbrexx3vqjhp51

Ring group identifier

query Parameters
expand[]
Array of strings
Items Value: "extensions"

Related resources to include inline. Supported values: extensions.

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
id
required
string

Unique identifier

name
required
string

Display name

timeout_seconds
required
integer [ 5 .. 300 ]

How long to ring members before giving up (seconds)

ignore_forwarding
required
boolean

When true, ignores SIP 302 redirects (call forwarding) from devices

confirm_external
required
boolean

When true, requires external (phone number) members to press a key before being connected

timeout_action
string or null
Enum: "ring_user" "voicemail" "queue" null

Action to take when the ring group times out:

  • ring_user — ring the fallback user.
  • voicemail — send to voicemail (the user's box or a shared box, determined by timeout_target).
  • queue — overflow the caller into a queue.
timeout_target
string or null

ID of the timeout target — a user, shared voicemail box, or queue, paired with timeout_action. Required when timeout_action is set.

object

List of extensions assigned to this ring group. Only included when expand[]=extensions is requested.

required
Array of objects (RingGroupMember)

List of members in this ring group

created_at
required
string <date-time> (CreatedAt)

Timestamp when it was created

updated_at
required
string <date-time> (UpdatedAt)

Timestamp when it was last updated

Request samples 

curl -X GET \
  'https://api.dialstack.ai/v1/ring_groups/rg_01h2xcejqtf2nbrexx3vqjhp51?expand%5B%5D=SOME_ARRAY_VALUE' \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "id": "rg_01h2xcejqtf2nbrexx3vqjhp51",
  • "name": "Sales Team",
  • "timeout_seconds": 30,
  • "ignore_forwarding": false,
  • "confirm_external": false,
  • "timeout_action": "voicemail",
  • "timeout_target": "user_01h2xcejqtf2nbrexx3vqjhp42",
  • "extensions": {
    },
  • "members": [
    ],
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

Update a ring group

Updates ring group settings. All fields are optional.

Authorizations:
BearerAuthSessionAuth
path Parameters
ring_group_id
required
string
Example: rg_01h2xcejqtf2nbrexx3vqjhp51

Ring group identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
name
string [ 1 .. 255 ] characters

New display name

timeout_seconds
integer [ 5 .. 300 ]

New timeout value

ignore_forwarding
boolean

New ignore_forwarding setting

confirm_external
boolean

New confirm_external setting

timeout_action
string or null
Enum: "ring_user" "voicemail" "queue" null

Action to take when the ring group times out:

  • ring_user — ring the fallback user.
  • voicemail — send to voicemail (the user's box or a shared box, determined by timeout_target).
  • queue — overflow the caller into a queue.

Send null together with a null timeout_target to clear the timeout configuration.

timeout_target
string or null

ID of the timeout target — a user, shared voicemail box, or queue, paired with timeout_action. Required when timeout_action is set.

Responses

Response Schema: application/json
id
required
string

Unique identifier

name
required
string

Display name

timeout_seconds
required
integer [ 5 .. 300 ]

How long to ring members before giving up (seconds)

ignore_forwarding
required
boolean

When true, ignores SIP 302 redirects (call forwarding) from devices

confirm_external
required
boolean

When true, requires external (phone number) members to press a key before being connected

timeout_action
string or null
Enum: "ring_user" "voicemail" "queue" null

Action to take when the ring group times out:

  • ring_user — ring the fallback user.
  • voicemail — send to voicemail (the user's box or a shared box, determined by timeout_target).
  • queue — overflow the caller into a queue.
timeout_target
string or null

ID of the timeout target — a user, shared voicemail box, or queue, paired with timeout_action. Required when timeout_action is set.

object

List of extensions assigned to this ring group. Only included when expand[]=extensions is requested.

required
Array of objects (RingGroupMember)

List of members in this ring group

created_at
required
string <date-time> (CreatedAt)

Timestamp when it was created

updated_at
required
string <date-time> (UpdatedAt)

Timestamp when it was last updated

Request samples

Content type
application/json
{
  • "name": "Support Team",
  • "timeout_seconds": 45,
  • "ignore_forwarding": true,
  • "confirm_external": true,
  • "timeout_action": "voicemail",
  • "timeout_target": "user_01h2xcejqtf2nbrexx3vqjhp42"
}

Response samples

Content type
application/json
{
  • "id": "rg_01h2xcejqtf2nbrexx3vqjhp51",
  • "name": "Sales Team",
  • "timeout_seconds": 30,
  • "ignore_forwarding": false,
  • "confirm_external": false,
  • "timeout_action": "voicemail",
  • "timeout_target": "user_01h2xcejqtf2nbrexx3vqjhp42",
  • "extensions": {
    },
  • "members": [
    ],
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

Delete a ring group

Deletes a ring group. Cannot delete if used by an extension.

Authorizations:
BearerAuthSessionAuth
path Parameters
ring_group_id
required
string
Example: rg_01h2xcejqtf2nbrexx3vqjhp51

Ring group identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Request samples 

curl -X DELETE \
  https://api.dialstack.ai/v1/ring_groups/rg_01h2xcejqtf2nbrexx3vqjhp51 \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "error": "Invalid request body",
  • "code": "validation_error",
  • "details": { }
}

Add a member

Adds a member to the ring group.

Exactly one of extension or phone_number must be provided:

  • extension: ID of a routing target
  • phone_number: Dial string (E.164, local number, extension, 911, etc.)
Authorizations:
BearerAuthSessionAuth
path Parameters
ring_group_id
required
string
Example: rg_01h2xcejqtf2nbrexx3vqjhp51

Ring group identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
extension
string

ID of a routing target

phone_number
string

Dial string (E.164, local number, extension, 911, etc.)

Responses

Response Schema: application/json
id
required
string

Unique identifier

ring_group_id
required
string

Unique identifier

extension
string or null

ID of a routing target

phone_number
string or null

Dial string (E.164, local number, extension, 911, etc.)

created_at
required
string <date-time> (CreatedAt)

Timestamp when it was created

Request samples

Content type
application/json
Example
{
  • "extension": "user_01h2xcejqtf2nbrexx3vqjhp42"
}

Response samples

Content type
application/json
{
  • "id": "rgm_01h2xcejqtf2nbrexx3vqjhp52",
  • "ring_group_id": "string",
  • "extension": "user_01h2xcejqtf2nbrexx3vqjhp42",
  • "phone_number": "+14155551234",
  • "created_at": "2025-10-17T14:30:00Z"
}

Remove a member

Removes a member from the ring group.

Authorizations:
BearerAuthSessionAuth
path Parameters
ring_group_id
required
string
Example: rg_01h2xcejqtf2nbrexx3vqjhp51

Ring group identifier

member_id
required
string
Example: rgm_01h2xcejqtf2nbrexx3vqjhp52

Ring group member identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Request samples 

curl -X DELETE \
  https://api.dialstack.ai/v1/ring_groups/rg_01h2xcejqtf2nbrexx3vqjhp51/members/rgm_01h2xcejqtf2nbrexx3vqjhp52 \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "error": "Invalid request body",
  • "code": "validation_error",
  • "details": { }
}

Call Queues

Call queue configuration, member management, and per-user agent state. Requires account context via DialStack-Account header or session token.

Create a call queue

Creates a new call queue. The queue starts with no members; add agents with POST /v1/queues/{queue_id}/members.

Authorizations:
BearerAuthSessionAuth
header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
name
required
string [ 1 .. 255 ] characters

Display name for the queue.

strategy
string
Enum: "ringall" "linear" "rrmemory" "leastrecent" "fewestcalls" "random" "wrandom"

Dispatch strategy. Defaults to ringall.

timeout_seconds
integer [ 0 .. 3600 ]
Default: 300

Caller wait limit before timeout fires. Defaults to 300 (5 minutes) so a caller can't sit forever if every eligible agent goes offline. When the timer fires, timeout decides what happens — null/omitted means hang up. Pass 0 to opt out of any timeout entirely (callers wait indefinitely until an agent picks up or they hang up).

wrap_up_seconds
integer [ 0 .. 600 ]

Per-agent cool-down after each call. Defaults to 0.

QueueAnnouncementsConfigInput (object) or null

Position-announcement config. Pass an object (with any subset of fields) to enable announcements; omit or pass null to disable.

QueueCallbackConfigInput (object) or null

Press-1 callback config. Pass an object (with any subset of fields) to enable callbacks; omit or pass null to disable.

QueueTimeout (any) or null

Fallback action when timeout_seconds elapses. Omitting or sending null means "hang up" — the timer still fires because timeout_seconds defaults to 300. To opt out of any timer, set timeout_seconds: 0; timeout is then ignored.

max_queue_length
integer >= 0

Maximum number of waiting callers. 0 = unlimited (default).

join_empty
string (QueueEmptyPolicy)
Enum: "strict" "no_agents_online" "no_agents_available"

Policy used by join_empty and leave_when_empty.

  • strict — apply the policy whenever no agents exist on the queue.
  • no_agents_online — apply when no agents are logged in.
  • no_agents_available — apply when no agents are available (logged in and not paused / in-call / wrapping up).
leave_when_empty
string (QueueEmptyPolicy)
Enum: "strict" "no_agents_online" "no_agents_available"

Policy used by join_empty and leave_when_empty.

  • strict — apply the policy whenever no agents exist on the queue.
  • no_agents_online — apply when no agents are logged in.
  • no_agents_available — apply when no agents are available (logged in and not paused / in-call / wrapping up).

Responses

Response Schema: application/json
id
required
string

Unique identifier

name
required
string

Display name

strategy
required
string (QueueStrategy)
Enum: "ringall" "linear" "rrmemory" "leastrecent" "fewestcalls" "random" "wrandom"

Dispatch strategy for selecting which agent to ring next.

  • ringall — ring every available agent in parallel; first to answer wins.
  • linear — ring agents in position order, lowest first.
  • rrmemory — round-robin with memory; resumes after the last agent dialed.
  • leastrecent — ring the agent who has not taken a call for the longest time.
  • fewestcalls — ring the agent with the fewest calls taken in the current window.
  • random — pick uniformly at random from available agents.
  • wrandom — weighted random; lower penalty is more likely to be picked.
timeout_seconds
required
integer [ 0 .. 3600 ]

How long a caller waits before the timeout action fires. 0 means no timeout — callers wait until an agent answers or they hang up.

wrap_up_seconds
required
integer [ 0 .. 600 ]

Cool-down per agent after each call ends, during which the agent is not eligible for dispatch. 0 disables wrap-up.

required
QueueAnnouncementsConfig (object) or null

Position-announcement configuration; null when announcements are disabled.

required
QueueCallbackConfig (object) or null

Press-1 callback configuration; null when callbacks are disabled

required
QueueTimeout (any) or null

Fallback action when timeout_seconds elapses. null means "hang up the caller" — the timer still fires when timeout_seconds > 0. To opt out of any timeout entirely (callers wait until an agent picks up or they hang up), set timeout_seconds to 0; timeout is then irrelevant.

max_queue_length
required
integer >= 0

Maximum number of callers waiting at once. 0 means unlimited. When the limit is reached, external callers hear a "queue full" announcement and are hung up; internal callers receive 486 Busy.

join_empty
required
string (QueueEmptyPolicy)
Enum: "strict" "no_agents_online" "no_agents_available"

Policy used by join_empty and leave_when_empty.

  • strict — apply the policy whenever no agents exist on the queue.
  • no_agents_online — apply when no agents are logged in.
  • no_agents_available — apply when no agents are available (logged in and not paused / in-call / wrapping up).
leave_when_empty
required
string (QueueEmptyPolicy)
Enum: "strict" "no_agents_online" "no_agents_available"

Policy used by join_empty and leave_when_empty.

  • strict — apply the policy whenever no agents exist on the queue.
  • no_agents_online — apply when no agents are logged in.
  • no_agents_available — apply when no agents are available (logged in and not paused / in-call / wrapping up).
required
object (EmbeddedQueueMembers)

Sub-collection of queue members embedded on the parent queue. Capped at 10 entries; use next_page_url (or GET /v1/queues/{queue_id}/members) to page through the rest.

object

Extensions assigned to this queue. Only included when expand[]=extensions is requested.

created_at
required
string <date-time> (CreatedAt)

Timestamp when it was created

updated_at
required
string <date-time> (UpdatedAt)

Timestamp when it was last updated

Request samples

Content type
application/json
Example
{
  • "name": "Support",
  • "strategy": "ringall",
  • "timeout_seconds": 120,
  • "wrap_up_seconds": 15,
  • "announcements": {
    },
  • "max_queue_length": 50,
  • "timeout": {
    }
}

Response samples

Content type
application/json
{
  • "id": "qu_01h2xcejqtf2nbrexx3vqjhp61",
  • "name": "Support",
  • "strategy": "ringall",
  • "timeout_seconds": 120,
  • "wrap_up_seconds": 15,
  • "announcements": {
    },
  • "callback": {
    },
  • "timeout": {
    },
  • "max_queue_length": 50,
  • "join_empty": "strict",
  • "leave_when_empty": "strict",
  • "members": {
    },
  • "extensions": {
    },
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

List call queues

Returns a paginated list of queues for the account.

Authorizations:
BearerAuthSessionAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

Number of objects to return. Defaults to 10. Maximum is 100.

expand[]
Array of strings
Items Value: "extensions"

Related resources to include inline. Supported values: extensions.

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
object
string (ListObject)
Value: "list"

String representing the object's type. Always "list" for list responses.

url
string (ListUrl)

The URL for accessing this list.

next_page_url
string or null (NextPageUrl)

URL to fetch the next page of results. If null, there are no more pages. The URL includes all necessary parameters including the pagination cursor.

previous_page_url
string or null (PreviousPageUrl)

URL to fetch the previous page of results. If null, this is the first page. The URL includes all necessary parameters including the pagination cursor.

Array of objects (Queue)

Request samples 

curl -X GET \
  'https://api.dialstack.ai/v1/queues?limit=10&expand%5B%5D=SOME_ARRAY_VALUE' \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "object": "list",
  • "url": "/v1/accounts",
  • "next_page_url": "/v1/accounts?page=eyJzdGFydGluZ19hZnRlciI6ImFjY3RfMDFoMnhjZWpxdGYybmJyZXh4M3ZxamhwNDEiLCJsaW1pdCI6MTB9",
  • "previous_page_url": "/v1/accounts?page=eyJlbmRpbmdfYmVmb3JlIjoiYWNjdF8wMWgyeGNlanF0ZjJuYnJleHgzdnFqaHA0MSIsImxpbWl0IjoxMH0",
  • "data": [
    ]
}

Get a call queue

Retrieves a queue by ID. The first 10 members are embedded inline under members; page through the rest via members.next_page_url or GET /v1/queues/{queue_id}/members.

Authorizations:
BearerAuthSessionAuth
path Parameters
queue_id
required
string
Example: qu_01h2xcejqtf2nbrexx3vqjhp61

Call queue identifier

query Parameters
expand[]
Array of strings
Items Value: "extensions"

Related resources to include inline. Supported values: extensions.

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
id
required
string

Unique identifier

name
required
string

Display name

strategy
required
string (QueueStrategy)
Enum: "ringall" "linear" "rrmemory" "leastrecent" "fewestcalls" "random" "wrandom"

Dispatch strategy for selecting which agent to ring next.

  • ringall — ring every available agent in parallel; first to answer wins.
  • linear — ring agents in position order, lowest first.
  • rrmemory — round-robin with memory; resumes after the last agent dialed.
  • leastrecent — ring the agent who has not taken a call for the longest time.
  • fewestcalls — ring the agent with the fewest calls taken in the current window.
  • random — pick uniformly at random from available agents.
  • wrandom — weighted random; lower penalty is more likely to be picked.
timeout_seconds
required
integer [ 0 .. 3600 ]

How long a caller waits before the timeout action fires. 0 means no timeout — callers wait until an agent answers or they hang up.

wrap_up_seconds
required
integer [ 0 .. 600 ]

Cool-down per agent after each call ends, during which the agent is not eligible for dispatch. 0 disables wrap-up.

required
QueueAnnouncementsConfig (object) or null

Position-announcement configuration; null when announcements are disabled.

required
QueueCallbackConfig (object) or null

Press-1 callback configuration; null when callbacks are disabled

required
QueueTimeout (any) or null

Fallback action when timeout_seconds elapses. null means "hang up the caller" — the timer still fires when timeout_seconds > 0. To opt out of any timeout entirely (callers wait until an agent picks up or they hang up), set timeout_seconds to 0; timeout is then irrelevant.

max_queue_length
required
integer >= 0

Maximum number of callers waiting at once. 0 means unlimited. When the limit is reached, external callers hear a "queue full" announcement and are hung up; internal callers receive 486 Busy.

join_empty
required
string (QueueEmptyPolicy)
Enum: "strict" "no_agents_online" "no_agents_available"

Policy used by join_empty and leave_when_empty.

  • strict — apply the policy whenever no agents exist on the queue.
  • no_agents_online — apply when no agents are logged in.
  • no_agents_available — apply when no agents are available (logged in and not paused / in-call / wrapping up).
leave_when_empty
required
string (QueueEmptyPolicy)
Enum: "strict" "no_agents_online" "no_agents_available"

Policy used by join_empty and leave_when_empty.

  • strict — apply the policy whenever no agents exist on the queue.
  • no_agents_online — apply when no agents are logged in.
  • no_agents_available — apply when no agents are available (logged in and not paused / in-call / wrapping up).
required
object (EmbeddedQueueMembers)

Sub-collection of queue members embedded on the parent queue. Capped at 10 entries; use next_page_url (or GET /v1/queues/{queue_id}/members) to page through the rest.

object

Extensions assigned to this queue. Only included when expand[]=extensions is requested.

created_at
required
string <date-time> (CreatedAt)

Timestamp when it was created

updated_at
required
string <date-time> (UpdatedAt)

Timestamp when it was last updated

Request samples 

curl -X GET \
  'https://api.dialstack.ai/v1/queues/qu_01h2xcejqtf2nbrexx3vqjhp61?expand%5B%5D=SOME_ARRAY_VALUE' \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "id": "qu_01h2xcejqtf2nbrexx3vqjhp61",
  • "name": "Support",
  • "strategy": "ringall",
  • "timeout_seconds": 120,
  • "wrap_up_seconds": 15,
  • "announcements": {
    },
  • "callback": {
    },
  • "timeout": {
    },
  • "max_queue_length": 50,
  • "join_empty": "strict",
  • "leave_when_empty": "strict",
  • "members": {
    },
  • "extensions": {
    },
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

Update a call queue

Updates queue settings. All fields are optional.

Send timeout: null to clear the timeout configuration; omit the field to leave it unchanged.

Authorizations:
BearerAuthSessionAuth
path Parameters
queue_id
required
string
Example: qu_01h2xcejqtf2nbrexx3vqjhp61

Call queue identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
name
string [ 1 .. 255 ] characters
strategy
string (QueueStrategy)
Enum: "ringall" "linear" "rrmemory" "leastrecent" "fewestcalls" "random" "wrandom"

Dispatch strategy for selecting which agent to ring next.

  • ringall — ring every available agent in parallel; first to answer wins.
  • linear — ring agents in position order, lowest first.
  • rrmemory — round-robin with memory; resumes after the last agent dialed.
  • leastrecent — ring the agent who has not taken a call for the longest time.
  • fewestcalls — ring the agent with the fewest calls taken in the current window.
  • random — pick uniformly at random from available agents.
  • wrandom — weighted random; lower penalty is more likely to be picked.
timeout_seconds
integer [ 0 .. 3600 ]
wrap_up_seconds
integer [ 0 .. 600 ]
QueueAnnouncementsConfigInput (object) or null

Position-announcement config. Pass null to disable; pass an object to enable/update. Omitted leaves the existing value untouched.

QueueCallbackConfigInput (object) or null

Press-1 callback config. Pass null to disable; pass an object to enable/update. Omitted leaves the existing value untouched.

QueueTimeout (any) or null

Send null to clear timeout behavior; omit to leave unchanged.

max_queue_length
integer >= 0
join_empty
string (QueueEmptyPolicy)
Enum: "strict" "no_agents_online" "no_agents_available"

Policy used by join_empty and leave_when_empty.

  • strict — apply the policy whenever no agents exist on the queue.
  • no_agents_online — apply when no agents are logged in.
  • no_agents_available — apply when no agents are available (logged in and not paused / in-call / wrapping up).
leave_when_empty
string (QueueEmptyPolicy)
Enum: "strict" "no_agents_online" "no_agents_available"

Policy used by join_empty and leave_when_empty.

  • strict — apply the policy whenever no agents exist on the queue.
  • no_agents_online — apply when no agents are logged in.
  • no_agents_available — apply when no agents are available (logged in and not paused / in-call / wrapping up).

Responses

Response Schema: application/json
id
required
string

Unique identifier

name
required
string

Display name

strategy
required
string (QueueStrategy)
Enum: "ringall" "linear" "rrmemory" "leastrecent" "fewestcalls" "random" "wrandom"

Dispatch strategy for selecting which agent to ring next.

  • ringall — ring every available agent in parallel; first to answer wins.
  • linear — ring agents in position order, lowest first.
  • rrmemory — round-robin with memory; resumes after the last agent dialed.
  • leastrecent — ring the agent who has not taken a call for the longest time.
  • fewestcalls — ring the agent with the fewest calls taken in the current window.
  • random — pick uniformly at random from available agents.
  • wrandom — weighted random; lower penalty is more likely to be picked.
timeout_seconds
required
integer [ 0 .. 3600 ]

How long a caller waits before the timeout action fires. 0 means no timeout — callers wait until an agent answers or they hang up.

wrap_up_seconds
required
integer [ 0 .. 600 ]

Cool-down per agent after each call ends, during which the agent is not eligible for dispatch. 0 disables wrap-up.

required
QueueAnnouncementsConfig (object) or null

Position-announcement configuration; null when announcements are disabled.

required
QueueCallbackConfig (object) or null

Press-1 callback configuration; null when callbacks are disabled

required
QueueTimeout (any) or null

Fallback action when timeout_seconds elapses. null means "hang up the caller" — the timer still fires when timeout_seconds > 0. To opt out of any timeout entirely (callers wait until an agent picks up or they hang up), set timeout_seconds to 0; timeout is then irrelevant.

max_queue_length
required
integer >= 0

Maximum number of callers waiting at once. 0 means unlimited. When the limit is reached, external callers hear a "queue full" announcement and are hung up; internal callers receive 486 Busy.

join_empty
required
string (QueueEmptyPolicy)
Enum: "strict" "no_agents_online" "no_agents_available"

Policy used by join_empty and leave_when_empty.

  • strict — apply the policy whenever no agents exist on the queue.
  • no_agents_online — apply when no agents are logged in.
  • no_agents_available — apply when no agents are available (logged in and not paused / in-call / wrapping up).
leave_when_empty
required
string (QueueEmptyPolicy)
Enum: "strict" "no_agents_online" "no_agents_available"

Policy used by join_empty and leave_when_empty.

  • strict — apply the policy whenever no agents exist on the queue.
  • no_agents_online — apply when no agents are logged in.
  • no_agents_available — apply when no agents are available (logged in and not paused / in-call / wrapping up).
required
object (EmbeddedQueueMembers)

Sub-collection of queue members embedded on the parent queue. Capped at 10 entries; use next_page_url (or GET /v1/queues/{queue_id}/members) to page through the rest.

object

Extensions assigned to this queue. Only included when expand[]=extensions is requested.

created_at
required
string <date-time> (CreatedAt)

Timestamp when it was created

updated_at
required
string <date-time> (UpdatedAt)

Timestamp when it was last updated

Request samples

Content type
application/json
Example
{
  • "timeout": null
}

Response samples

Content type
application/json
{
  • "id": "qu_01h2xcejqtf2nbrexx3vqjhp61",
  • "name": "Support",
  • "strategy": "ringall",
  • "timeout_seconds": 120,
  • "wrap_up_seconds": 15,
  • "announcements": {
    },
  • "callback": {
    },
  • "timeout": {
    },
  • "max_queue_length": 50,
  • "join_empty": "strict",
  • "leave_when_empty": "strict",
  • "members": {
    },
  • "extensions": {
    },
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

Delete a call queue

Deletes a queue and removes all of its members.

Authorizations:
BearerAuthSessionAuth
path Parameters
queue_id
required
string
Example: qu_01h2xcejqtf2nbrexx3vqjhp61

Call queue identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Request samples 

curl -X DELETE \
  https://api.dialstack.ai/v1/queues/qu_01h2xcejqtf2nbrexx3vqjhp61 \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "error": "Invalid request body",
  • "code": "validation_error",
  • "details": { }
}

List queue members

Returns a paginated list of members on the queue.

Authorizations:
BearerAuthSessionAuth
path Parameters
queue_id
required
string
Example: qu_01h2xcejqtf2nbrexx3vqjhp61

Call queue identifier

query Parameters
limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

Number of objects to return. Defaults to 10. Maximum is 100.

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
object
string (ListObject)
Value: "list"

String representing the object's type. Always "list" for list responses.

url
string (ListUrl)

The URL for accessing this list.

next_page_url
string or null (NextPageUrl)

URL to fetch the next page of results. If null, there are no more pages. The URL includes all necessary parameters including the pagination cursor.

previous_page_url
string or null (PreviousPageUrl)

URL to fetch the previous page of results. If null, this is the first page. The URL includes all necessary parameters including the pagination cursor.

Array of objects (QueueMember)

Request samples 

curl -X GET \
  'https://api.dialstack.ai/v1/queues/qu_01h2xcejqtf2nbrexx3vqjhp61/members?limit=10' \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "object": "list",
  • "url": "/v1/accounts",
  • "next_page_url": "/v1/accounts?page=eyJzdGFydGluZ19hZnRlciI6ImFjY3RfMDFoMnhjZWpxdGYybmJyZXh4M3ZxamhwNDEiLCJsaW1pdCI6MTB9",
  • "previous_page_url": "/v1/accounts?page=eyJlbmRpbmdfYmVmb3JlIjoiYWNjdF8wMWgyeGNlanF0ZjJuYnJleHgzdnFqaHA0MSIsImxpbWl0IjoxMH0",
  • "data": [
    ]
}

Add a queue member

Adds a user agent to the queue. Each user can be a member of a queue at most once; re-adding returns 409.

Auto-login side effect. On success, the user is also marked logged in for queue dispatch (equivalent to dialing *45) so they start receiving queue calls immediately — admins don't have to log agents in separately. The auto-login is conservative:

  • Agents who are already logged in are unaffected (no-op).
  • Paused agents stay paused. Adding someone to another queue while they're on a break doesn't end the break.
  • Logged-out agents and users who have never had queue state are marked available.

Agents can still log themselves out with *45 or via the POST /v1/users/{user_id}/queue-agent endpoint.

Authorizations:
BearerAuthSessionAuth
path Parameters
queue_id
required
string
Example: qu_01h2xcejqtf2nbrexx3vqjhp61

Call queue identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
user_id
required
string

User TypeID (user_...) of the agent to add.

penalty
integer >= 0

Strategy hint. Defaults to 0.

position
integer >= 1

1-based insertion position. Defaults to the end of the queue.

Responses

Response Schema: application/json
id
required
string

Unique identifier

queue_id
required
string

Unique identifier

user_id
required
string

Unique identifier

penalty
required
integer >= 0

Strategy hint. Lower-penalty agents are preferred by linear, wrandom, and tie-breakers in other strategies. Defaults to 0.

position
required
integer >= 1

1-based ordering within the queue, used by linear and rrmemory for deterministic rotation. Members default to the next free position; pass an explicit position to insert mid-list.

created_at
required
string <date-time> (CreatedAt)

Timestamp when it was created

Request samples

Content type
application/json
Example
{
  • "user_id": "user_01h2xcejqtf2nbrexx3vqjhp42"
}

Response samples

Content type
application/json
{
  • "id": "qum_01h2xcejqtf2nbrexx3vqjhp62",
  • "queue_id": "qu_01h2xcejqtf2nbrexx3vqjhp61",
  • "user_id": "user_01h2xcejqtf2nbrexx3vqjhp42",
  • "penalty": 0,
  • "position": 3,
  • "created_at": "2025-10-17T14:30:00Z"
}

Remove a queue member

Removes a member from the queue.

Authorizations:
BearerAuthSessionAuth
path Parameters
queue_id
required
string
Example: qu_01h2xcejqtf2nbrexx3vqjhp61

Call queue identifier

member_id
required
string
Example: qum_01h2xcejqtf2nbrexx3vqjhp62

Queue member identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Request samples 

curl -X DELETE \
  https://api.dialstack.ai/v1/queues/qu_01h2xcejqtf2nbrexx3vqjhp61/members/qum_01h2xcejqtf2nbrexx3vqjhp62 \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "error": "Invalid request body",
  • "code": "validation_error",
  • "details": { }
}

Get queue-agent state

Returns the user's current queue-agent operational state. status is derived from the underlying timestamps: paused_at present renders as paused; logged_in_at absent renders as logged_out; otherwise available.

Returns 404 if the user has never had agent state written. A user who logged out is not a 404 — the row is retained so historical attributes survive the logout/login cycle.

Authorizations:
BearerAuthSessionAuth
path Parameters
user_id
required
string
Example: user_01h2xcejqtf2nbrexx3vqjhp42

User identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
user_id
required
string

The agent (user) this status belongs to

status
required
string
Enum: "available" "paused" "logged_out"

Current availability state

paused_at
string <date-time>

When the agent entered the paused state, if applicable

pause_reason
string

Free-form reason for the current pause, if provided

logged_in_at
string <date-time>

When the agent first logged in to the queue

in_call_since
string <date-time>

When the agent's currently-active call started, if any

updated_at
required
string <date-time>

Timestamp when it was last updated

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/users/user_01h2xcejqtf2nbrexx3vqjhp42/queue-agent \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "user_id": "user_01h2xcejqtf2nbrexx3vqjhp42",
  • "status": "paused",
  • "paused_at": "2019-08-24T14:15:22Z",
  • "pause_reason": "break",
  • "logged_in_at": "2019-08-24T14:15:22Z",
  • "in_call_since": "2019-08-24T14:15:22Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

Update queue-agent state

Sets a queue agent's availability state. The endpoint is idempotent: re-sending the current status is a 200 with no semantic change.

Transitioning to available (or paused) from a logged-out state sets logged_in_at if it isn't already populated; subsequent flips between available and paused preserve the original login time. Transitioning to logged_out clears logged_in_at, paused_at, and pause_reason but retains the row so historical attributes survive the logout/login cycle.

reason is only valid when status is paused; sending it with any other status returns 400.

Authorizations:
BearerAuthSessionAuth
path Parameters
user_id
required
string
Example: user_01h2xcejqtf2nbrexx3vqjhp42

User identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
status
required
string
Enum: "available" "paused" "logged_out"

Target availability state:

  • available — the agent is logged in and eligible to receive calls
  • paused — the agent is logged in but temporarily unavailable
  • logged_out — the agent is not signed in to the queue
reason
string <= 255 characters

Optional free-form reason associated with a paused state (e.g., break, lunch, training). Only allowed when status is paused.

Responses

Response Schema: application/json
user_id
required
string

The agent (user) this status belongs to

status
required
string
Enum: "available" "paused" "logged_out"

Current availability state

paused_at
string <date-time>

When the agent entered the paused state, if applicable

pause_reason
string

Free-form reason for the current pause, if provided

logged_in_at
string <date-time>

When the agent first logged in to the queue

in_call_since
string <date-time>

When the agent's currently-active call started, if any

updated_at
required
string <date-time>

Timestamp when it was last updated

Request samples

Content type
application/json
Example
{
  • "status": "paused",
  • "reason": "break"
}

Response samples

Content type
application/json
{
  • "user_id": "user_01h2xcejqtf2nbrexx3vqjhp42",
  • "status": "paused",
  • "paused_at": "2019-08-24T14:15:22Z",
  • "pause_reason": "break",
  • "logged_in_at": "2019-08-24T14:15:22Z",
  • "in_call_since": "2019-08-24T14:15:22Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

Schedules

Business hours schedule management. Schedules define when the business is open based on weekly time ranges and holidays. A temporary hold can override the schedule calculation. Requires account context via DialStack-Account header or session token.

Create a schedule

Create a new business hours schedule within the account. Schedules define when the business is open based on weekly time ranges and holidays.

Authorizations:
BearerAuthSessionAuth
header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
name
required
string [ 1 .. 255 ] characters

Display name for the schedule

timezone
string

IANA timezone for interpreting times (e.g., "America/New_York")

required
Array of objects (TimeRange)

Weekly time ranges when the schedule is considered "open"

Array of objects (DateRange)

Date ranges when the schedule is closed regardless of weekly ranges

Responses

Response Schema: application/json
id
required
string

Unique identifier

name
required
string [ 1 .. 255 ] characters

Display name for the schedule

timezone
string or null

IANA timezone for interpreting times (e.g., "America/New_York"). If null, uses account default.

required
Array of objects (TimeRange)

Weekly time ranges when the schedule is considered "open"

Array of objects (DateRange)

Date ranges when the schedule is closed regardless of weekly ranges

ScheduleHold (object) or null

Temporary override for the schedule

created_at
required
string <date-time>

Timestamp when it was created

updated_at
string <date-time>

Timestamp when it was last updated

Request samples

Content type
application/json
{
  • "name": "Business Hours",
  • "timezone": "America/New_York",
  • "ranges": [
    ],
  • "holidays": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "sched_01h2xcejqtf2nbrexx3vqjhp50",
  • "name": "Business Hours",
  • "timezone": "America/New_York",
  • "ranges": [
    ],
  • "holidays": [ ],
  • "created_at": "2025-10-18T10:00:00Z",
  • "updated_at": "2025-10-18T10:00:00Z"
}

List schedules

List all schedules for the account. Results are returned in reverse chronological order (newest first).

Authorizations:
BearerAuthSessionAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

Number of objects to return. Defaults to 10. Maximum is 100.

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
object
required
string (ListObject)
Value: "list"

String representing the object's type. Always "list" for list responses.

url
required
string (ListUrl)

The URL for accessing this list.

next_page_url
required
string or null (NextPageUrl)

URL to fetch the next page of results. If null, there are no more pages. The URL includes all necessary parameters including the pagination cursor.

previous_page_url
required
string or null (PreviousPageUrl)

URL to fetch the previous page of results. If null, this is the first page. The URL includes all necessary parameters including the pagination cursor.

required
Array of objects (Schedule)

Request samples 

curl -X GET \
  'https://api.dialstack.ai/v1/schedules?limit=10' \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "object": "list",
  • "url": "/v1/schedules",
  • "next_page_url": null,
  • "previous_page_url": null,
  • "data": [
    ]
}

Get schedule details

Retrieve a specific schedule by ID.

Authorizations:
BearerAuthSessionAuth
path Parameters
schedule_id
required
string
Example: sched_01h2xcejqtf2nbrexx3vqjhp50

Schedule identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
id
required
string

Unique identifier

name
required
string [ 1 .. 255 ] characters

Display name for the schedule

timezone
string or null

IANA timezone for interpreting times (e.g., "America/New_York"). If null, uses account default.

required
Array of objects (TimeRange)

Weekly time ranges when the schedule is considered "open"

Array of objects (DateRange)

Date ranges when the schedule is closed regardless of weekly ranges

ScheduleHold (object) or null

Temporary override for the schedule

created_at
required
string <date-time>

Timestamp when it was created

updated_at
string <date-time>

Timestamp when it was last updated

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/schedules/sched_01h2xcejqtf2nbrexx3vqjhp50 \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "id": "sched_01h2xcejqtf2nbrexx3vqjhp50",
  • "name": "Business Hours",
  • "timezone": "America/New_York",
  • "ranges": [
    ],
  • "holidays": [
    ],
  • "hold": {
    },
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

Update schedule

Update schedule details (name, timezone, ranges, or holidays). Only the fields provided will be updated.

Authorizations:
BearerAuthSessionAuth
path Parameters
schedule_id
required
string
Example: sched_01h2xcejqtf2nbrexx3vqjhp50

Schedule identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
name
string [ 1 .. 255 ] characters

Display name for the schedule

timezone
string

IANA timezone for interpreting times

Array of objects (TimeRange)

Weekly time ranges when the schedule is considered "open"

Array of objects (DateRange)

Date ranges when the schedule is closed regardless of weekly ranges

Responses

Response Schema: application/json
id
required
string

Unique identifier

name
required
string [ 1 .. 255 ] characters

Display name for the schedule

timezone
string or null

IANA timezone for interpreting times (e.g., "America/New_York"). If null, uses account default.

required
Array of objects (TimeRange)

Weekly time ranges when the schedule is considered "open"

Array of objects (DateRange)

Date ranges when the schedule is closed regardless of weekly ranges

ScheduleHold (object) or null

Temporary override for the schedule

created_at
required
string <date-time>

Timestamp when it was created

updated_at
string <date-time>

Timestamp when it was last updated

Request samples

Content type
application/json
Example
{
  • "name": "New Business Hours"
}

Response samples

Content type
application/json
{
  • "id": "sched_01h2xcejqtf2nbrexx3vqjhp50",
  • "name": "Business Hours",
  • "timezone": "America/New_York",
  • "ranges": [
    ],
  • "holidays": [
    ],
  • "hold": {
    },
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

Delete schedule

Delete a schedule. This operation is irreversible.

Authorizations:
BearerAuthSessionAuth
path Parameters
schedule_id
required
string
Example: sched_01h2xcejqtf2nbrexx3vqjhp50

Schedule identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Request samples 

curl -X DELETE \
  https://api.dialstack.ai/v1/schedules/sched_01h2xcejqtf2nbrexx3vqjhp50 \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "error": "Invalid request body",
  • "code": "validation_error",
  • "details": { }
}

Set schedule hold

Set a temporary hold on a schedule. The hold overrides the normal schedule calculation until the specified time.

Use value: true to force the schedule to be considered "open" regardless of the time ranges, or value: false to force it to be considered "closed".

If until is not provided, it defaults to midnight (00:00:00) the next day in the schedule's timezone.

Authorizations:
BearerAuthSessionAuth
path Parameters
schedule_id
required
string
Example: sched_01h2xcejqtf2nbrexx3vqjhp50

Schedule identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
value
required
boolean

Override value (true=force open, false=force closed)

until
string <date-time-local>

When the hold expires. Interpreted in the schedule's timezone. If not provided, defaults to midnight (00:00:00) the next day.

Responses

Response Schema: application/json
id
required
string

Unique identifier

name
required
string [ 1 .. 255 ] characters

Display name for the schedule

timezone
string or null

IANA timezone for interpreting times (e.g., "America/New_York"). If null, uses account default.

required
Array of objects (TimeRange)

Weekly time ranges when the schedule is considered "open"

Array of objects (DateRange)

Date ranges when the schedule is closed regardless of weekly ranges

ScheduleHold (object) or null

Temporary override for the schedule

created_at
required
string <date-time>

Timestamp when it was created

updated_at
string <date-time>

Timestamp when it was last updated

Request samples

Content type
application/json
Example
{
  • "value": false,
  • "until": "2025-12-20T17:00:00"
}

Response samples

Content type
application/json
{
  • "id": "sched_01h2xcejqtf2nbrexx3vqjhp50",
  • "name": "Business Hours",
  • "timezone": "America/New_York",
  • "ranges": [
    ],
  • "holidays": [ ],
  • "hold": {
    },
  • "created_at": "2025-10-18T10:00:00Z",
  • "updated_at": "2025-10-18T14:30:00Z"
}

Clear schedule hold

Clear the hold from a schedule, returning it to normal schedule-based calculation.

Authorizations:
BearerAuthSessionAuth
path Parameters
schedule_id
required
string
Example: sched_01h2xcejqtf2nbrexx3vqjhp50

Schedule identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
id
required
string

Unique identifier

name
required
string [ 1 .. 255 ] characters

Display name for the schedule

timezone
string or null

IANA timezone for interpreting times (e.g., "America/New_York"). If null, uses account default.

required
Array of objects (TimeRange)

Weekly time ranges when the schedule is considered "open"

Array of objects (DateRange)

Date ranges when the schedule is closed regardless of weekly ranges

ScheduleHold (object) or null

Temporary override for the schedule

created_at
required
string <date-time>

Timestamp when it was created

updated_at
string <date-time>

Timestamp when it was last updated

Request samples 

curl -X DELETE \
  https://api.dialstack.ai/v1/schedules/sched_01h2xcejqtf2nbrexx3vqjhp50/hold \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "id": "sched_01h2xcejqtf2nbrexx3vqjhp50",
  • "name": "Business Hours",
  • "timezone": "America/New_York",
  • "ranges": [
    ],
  • "holidays": [ ],
  • "created_at": "2025-10-18T10:00:00Z",
  • "updated_at": "2025-10-18T14:35:00Z"
}

Shared Voicemail Boxes

Shared voicemail box management for team or departmental voicemail. Shared voicemail boxes can receive messages and forward them via email. Requires account context via DialStack-Account header or session token.

Create a shared voicemail box

Creates a new shared voicemail box for team or departmental voicemail.

Authorizations:
BearerAuthSessionAuth
header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
name
required
string [ 1 .. 255 ] characters

Display name for the shared voicemail box

email
string

Email address to send voicemail notifications to

pin
string^\d{4,10}$

PIN code for accessing the voicemail box (4-10 digits)

email_attach_audio
boolean

Whether to attach the audio recording to notification emails (defaults to true)

email_include_summary
boolean

Whether to include a summary in notification emails (defaults to true)

email_include_transcript
boolean

Whether to include a transcript in notification emails (defaults to true)

delete_after_email
boolean

Whether to delete the voicemail after sending the email notification (defaults to true)

Responses

Response Schema: application/json
id
required
string

Unique identifier

name
required
string

Display name

email
string or null

Email address to send voicemail notifications to

pin
string or null

PIN code for accessing the voicemail box (4-10 digits)

email_attach_audio
required
boolean

Whether to attach the audio recording to notification emails

email_include_summary
required
boolean

Whether to include a summary in notification emails

email_include_transcript
required
boolean

Whether to include a transcript in notification emails

delete_after_email
required
boolean

Whether to delete the voicemail after sending the email notification

object

List of extensions assigned to this shared voicemail box. Only included when expand[]=extensions is requested.

created_at
required
string <date-time> (CreatedAt)

Timestamp when it was created

updated_at
required
string <date-time> (UpdatedAt)

Timestamp when it was last updated

Request samples

Content type
application/json
{
  • "name": "Sales Voicemail",
  • "email": "sales@example.com",
  • "pin": "1234",
  • "email_attach_audio": true,
  • "email_include_summary": true,
  • "email_include_transcript": true,
  • "delete_after_email": true
}

Response samples

Content type
application/json
{
  • "id": "svm_01h2xcejqtf2nbrexx3vqjhp60",
  • "name": "Sales Voicemail",
  • "email": "sales@example.com",
  • "pin": "1234",
  • "email_attach_audio": true,
  • "email_include_summary": true,
  • "email_include_transcript": true,
  • "delete_after_email": true,
  • "extensions": {
    },
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

List shared voicemail boxes

Returns a paginated list of shared voicemail boxes for the account.

Authorizations:
BearerAuthSessionAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

Number of objects to return. Defaults to 10. Maximum is 100.

expand[]
Array of strings
Items Value: "extensions"

Related resources to include inline. Supported values: extensions.

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
object
string (ListObject)
Value: "list"

String representing the object's type. Always "list" for list responses.

url
string (ListUrl)

The URL for accessing this list.

next_page_url
string or null (NextPageUrl)

URL to fetch the next page of results. If null, there are no more pages. The URL includes all necessary parameters including the pagination cursor.

previous_page_url
string or null (PreviousPageUrl)

URL to fetch the previous page of results. If null, this is the first page. The URL includes all necessary parameters including the pagination cursor.

Array of objects (SharedVoicemailBox)

Request samples 

curl -X GET \
  'https://api.dialstack.ai/v1/shared_voicemail_boxes?limit=10&expand%5B%5D=SOME_ARRAY_VALUE' \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "object": "list",
  • "url": "/v1/accounts",
  • "next_page_url": "/v1/accounts?page=eyJzdGFydGluZ19hZnRlciI6ImFjY3RfMDFoMnhjZWpxdGYybmJyZXh4M3ZxamhwNDEiLCJsaW1pdCI6MTB9",
  • "previous_page_url": "/v1/accounts?page=eyJlbmRpbmdfYmVmb3JlIjoiYWNjdF8wMWgyeGNlanF0ZjJuYnJleHgzdnFqaHA0MSIsImxpbWl0IjoxMH0",
  • "data": [
    ]
}

Get a shared voicemail box

Retrieves a shared voicemail box by ID.

Authorizations:
BearerAuthSessionAuth
path Parameters
shared_voicemail_box_id
required
string
Example: svm_01h2xcejqtf2nbrexx3vqjhp60

Shared voicemail box identifier

query Parameters
expand[]
Array of strings
Items Value: "extensions"

Related resources to include inline. Supported values: extensions.

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
id
required
string

Unique identifier

name
required
string

Display name

email
string or null

Email address to send voicemail notifications to

pin
string or null

PIN code for accessing the voicemail box (4-10 digits)

email_attach_audio
required
boolean

Whether to attach the audio recording to notification emails

email_include_summary
required
boolean

Whether to include a summary in notification emails

email_include_transcript
required
boolean

Whether to include a transcript in notification emails

delete_after_email
required
boolean

Whether to delete the voicemail after sending the email notification

object

List of extensions assigned to this shared voicemail box. Only included when expand[]=extensions is requested.

created_at
required
string <date-time> (CreatedAt)

Timestamp when it was created

updated_at
required
string <date-time> (UpdatedAt)

Timestamp when it was last updated

Request samples 

curl -X GET \
  'https://api.dialstack.ai/v1/shared_voicemail_boxes/svm_01h2xcejqtf2nbrexx3vqjhp60?expand%5B%5D=SOME_ARRAY_VALUE' \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "id": "svm_01h2xcejqtf2nbrexx3vqjhp60",
  • "name": "Sales Voicemail",
  • "email": "sales@example.com",
  • "pin": "1234",
  • "email_attach_audio": true,
  • "email_include_summary": true,
  • "email_include_transcript": true,
  • "delete_after_email": true,
  • "extensions": {
    },
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

Update a shared voicemail box

Updates shared voicemail box settings. All fields are optional.

Authorizations:
BearerAuthSessionAuth
path Parameters
shared_voicemail_box_id
required
string
Example: svm_01h2xcejqtf2nbrexx3vqjhp60

Shared voicemail box identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
name
string [ 1 .. 255 ] characters

New display name

email
string or null

Email address to send voicemail notifications to

pin
string or null^\d{4,10}$

PIN code for accessing the voicemail box (4-10 digits)

email_attach_audio
boolean

Whether to attach the audio recording to notification emails

email_include_summary
boolean

Whether to include a summary in notification emails

email_include_transcript
boolean

Whether to include a transcript in notification emails

delete_after_email
boolean

Whether to delete the voicemail after sending the email notification

Responses

Response Schema: application/json
id
required
string

Unique identifier

name
required
string

Display name

email
string or null

Email address to send voicemail notifications to

pin
string or null

PIN code for accessing the voicemail box (4-10 digits)

email_attach_audio
required
boolean

Whether to attach the audio recording to notification emails

email_include_summary
required
boolean

Whether to include a summary in notification emails

email_include_transcript
required
boolean

Whether to include a transcript in notification emails

delete_after_email
required
boolean

Whether to delete the voicemail after sending the email notification

object

List of extensions assigned to this shared voicemail box. Only included when expand[]=extensions is requested.

created_at
required
string <date-time> (CreatedAt)

Timestamp when it was created

updated_at
required
string <date-time> (UpdatedAt)

Timestamp when it was last updated

Request samples

Content type
application/json
{
  • "name": "Support Voicemail",
  • "email": "support@example.com",
  • "pin": "5678",
  • "email_attach_audio": false,
  • "email_include_summary": false,
  • "email_include_transcript": false,
  • "delete_after_email": false
}

Response samples

Content type
application/json
{
  • "id": "svm_01h2xcejqtf2nbrexx3vqjhp60",
  • "name": "Sales Voicemail",
  • "email": "sales@example.com",
  • "pin": "1234",
  • "email_attach_audio": true,
  • "email_include_summary": true,
  • "email_include_transcript": true,
  • "delete_after_email": true,
  • "extensions": {
    },
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

Delete a shared voicemail box

Deletes a shared voicemail box. Cannot delete if used by an extension.

Authorizations:
BearerAuthSessionAuth
path Parameters
shared_voicemail_box_id
required
string
Example: svm_01h2xcejqtf2nbrexx3vqjhp60

Shared voicemail box identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Request samples 

curl -X DELETE \
  https://api.dialstack.ai/v1/shared_voicemail_boxes/svm_01h2xcejqtf2nbrexx3vqjhp60 \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "error": "Invalid request body",
  • "code": "validation_error",
  • "details": { }
}

Audio Clips

Audio clip management for hold music, IVR prompts, and other audio playback. Upload audio files which are validated and transcoded server-side. Requires account context via DialStack-Account header or session token.

Upload an audio clip

Uploads a new audio clip for use as hold music, IVR prompts, or other audio playback.

Accepts a multipart form with a file field (audio file) and a name field (display name). The audio is validated and transcoded server-side. Maximum file size: 5 MB. Supported input formats: WAV, MP3, AAC, Ogg Vorbis, Opus.

Authorizations:
BearerAuthSessionAuth
header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: multipart/form-data
required
name
required
string [ 1 .. 255 ] characters

Display name for the audio clip (must be unique per account)

file
required
string <binary>

Audio file to upload

Responses

Response Schema: application/json
id
required
string

Unique identifier

name
required
string

Display name (unique per account)

url
required
string

Signed URL for downloading the audio file (expires after 5 minutes)

mime_type
required
string

MIME type of the stored audio file

duration_ms
required
integer

Duration of the audio clip in milliseconds

size_bytes
required
integer <int64>

Size of the stored audio file in bytes

source_sha256
string or null

SHA-256 hash of the original uploaded file (before transcoding)

created_at
required
string <date-time> (CreatedAt)

Timestamp when it was created

updated_at
required
string <date-time> (UpdatedAt)

Timestamp when it was last updated

Request samples 

curl -X POST \
  https://api.dialstack.ai/v1/audio_clips \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41' \
  -H 'content-type: multipart/form-data' \
  --form 'name=Hold Music' \
  --form file=string

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "Hold Music",
  • "url": "https://cdn.example.com/audio-clips/clip.wav?Expires=...",
  • "mime_type": "audio/wav",
  • "duration_ms": 30000,
  • "size_bytes": 240000,
  • "source_sha256": "113a95dbbfd24492fb4e527b58d64aece235d6a5057ea671dbf2fe980a9cf6a3",
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

List audio clips

Returns a paginated list of audio clips for the account.

Authorizations:
BearerAuthSessionAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

Number of objects to return. Defaults to 10. Maximum is 100.

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
object
string (ListObject)
Value: "list"

String representing the object's type. Always "list" for list responses.

url
string (ListUrl)

The URL for accessing this list.

next_page_url
string or null (NextPageUrl)

URL to fetch the next page of results. If null, there are no more pages. The URL includes all necessary parameters including the pagination cursor.

previous_page_url
string or null (PreviousPageUrl)

URL to fetch the previous page of results. If null, this is the first page. The URL includes all necessary parameters including the pagination cursor.

Array of objects (AudioClip)

Request samples 

curl -X GET \
  'https://api.dialstack.ai/v1/audio_clips?limit=10' \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "object": "list",
  • "url": "/v1/accounts",
  • "next_page_url": "/v1/accounts?page=eyJzdGFydGluZ19hZnRlciI6ImFjY3RfMDFoMnhjZWpxdGYybmJyZXh4M3ZxamhwNDEiLCJsaW1pdCI6MTB9",
  • "previous_page_url": "/v1/accounts?page=eyJlbmRpbmdfYmVmb3JlIjoiYWNjdF8wMWgyeGNlanF0ZjJuYnJleHgzdnFqaHA0MSIsImxpbWl0IjoxMH0",
  • "data": [
    ]
}

Get an audio clip

Retrieves an audio clip by ID. The response includes a signed URL for downloading the audio file.

Authorizations:
BearerAuthSessionAuth
path Parameters
audio_clip_id
required
string

Audio clip identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
id
required
string

Unique identifier

name
required
string

Display name (unique per account)

url
required
string

Signed URL for downloading the audio file (expires after 5 minutes)

mime_type
required
string

MIME type of the stored audio file

duration_ms
required
integer

Duration of the audio clip in milliseconds

size_bytes
required
integer <int64>

Size of the stored audio file in bytes

source_sha256
string or null

SHA-256 hash of the original uploaded file (before transcoding)

created_at
required
string <date-time> (CreatedAt)

Timestamp when it was created

updated_at
required
string <date-time> (UpdatedAt)

Timestamp when it was last updated

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/audio_clips/%7Baudio_clip_id%7D \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "Hold Music",
  • "url": "https://cdn.example.com/audio-clips/clip.wav?Expires=...",
  • "mime_type": "audio/wav",
  • "duration_ms": 30000,
  • "size_bytes": 240000,
  • "source_sha256": "113a95dbbfd24492fb4e527b58d64aece235d6a5057ea671dbf2fe980a9cf6a3",
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

Update an audio clip

Updates an audio clip's display name.

Authorizations:
BearerAuthSessionAuth
path Parameters
audio_clip_id
required
string

Audio clip identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
name
string [ 1 .. 255 ] characters

New display name

Responses

Response Schema: application/json
id
required
string

Unique identifier

name
required
string

Display name (unique per account)

url
required
string

Signed URL for downloading the audio file (expires after 5 minutes)

mime_type
required
string

MIME type of the stored audio file

duration_ms
required
integer

Duration of the audio clip in milliseconds

size_bytes
required
integer <int64>

Size of the stored audio file in bytes

source_sha256
string or null

SHA-256 hash of the original uploaded file (before transcoding)

created_at
required
string <date-time> (CreatedAt)

Timestamp when it was created

updated_at
required
string <date-time> (UpdatedAt)

Timestamp when it was last updated

Request samples

Content type
application/json
{
  • "name": "Updated Hold Music"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "Hold Music",
  • "url": "https://cdn.example.com/audio-clips/clip.wav?Expires=...",
  • "mime_type": "audio/wav",
  • "duration_ms": 30000,
  • "size_bytes": 240000,
  • "source_sha256": "113a95dbbfd24492fb4e527b58d64aece235d6a5057ea671dbf2fe980a9cf6a3",
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

Delete an audio clip

Deletes an audio clip.

Authorizations:
BearerAuthSessionAuth
path Parameters
audio_clip_id
required
string

Audio clip identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Request samples 

curl -X DELETE \
  https://api.dialstack.ai/v1/audio_clips/%7Baudio_clip_id%7D \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "error": "Invalid request body",
  • "code": "validation_error",
  • "details": { }
}

Phone Numbers

Phone number (DID) management including search, ordering, and disconnect. Requires account context via DialStack-Account header or session token. For porting existing numbers from another carrier, see Number Porting.

List phone numbers

List all phone numbers assigned to the account. Results are returned in reverse chronological order (newest first).

Authorizations:
BearerAuthSessionAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

Number of objects to return. Defaults to 10. Maximum is 100.

status
string
Enum: "active" "inactive" "pending" "released"
Example: status=active

Filter by phone number status

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
object
required
string (ListObject)
Value: "list"

String representing the object's type. Always "list" for list responses.

url
required
string (ListUrl)

The URL for accessing this list.

next_page_url
required
string or null (NextPageUrl)

URL to fetch the next page of results. If null, there are no more pages. The URL includes all necessary parameters including the pagination cursor.

previous_page_url
required
string or null (PreviousPageUrl)

URL to fetch the previous page of results. If null, this is the first page. The URL includes all necessary parameters including the pagination cursor.

required
Array of objects (PhoneNumber)

Request samples 

curl -X GET \
  'https://api.dialstack.ai/v1/phone-numbers?limit=10&status=active' \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "object": "list",
  • "url": "/v1/phone-numbers",
  • "next_page_url": null,
  • "previous_page_url": null,
  • "data": [
    ]
}

Get a phone number

Retrieve a phone number by ID.

Authorizations:
BearerAuthSessionAuth
path Parameters
phone_number_id
required
string
Example: did_01h2xcejqtf2nbrexx3vqjhp46

Phone number identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
id
required
string

Unique identifier

phone_number
required
string <= 20 characters

Phone number in E.164 format

status
required
string
Enum: "active" "inactive" "released"

Current status of the phone number

outbound_enabled
required
boolean

Whether this phone number can be used for outbound calling

expires_at
required
string or null <date-time>

When the phone number is scheduled to be released back to the carrier. Set on temporary numbers issued during signup; null on permanent numbers.

disconnected_at
required
string or null <date-time>

When the phone number was released back to the carrier. Null while the number is in service.

caller_id_name
string or null <= 15 characters

The caller ID name (CNAM) configured for this phone number, or null if not set

directory_listing_name
string or null

The business name used for directory listing (411/white pages), or null if not set

directory_listing_type
string
Enum: "listed" "non_listed" "non_published" "non_registered"

How the number appears in directory services

directory_listing_location_id
string or null

ID of the location whose address is published in the directory listing, or null

routing_target
required
string or null

ID of the target that inbound calls to this number are routed to, or null if no routing is configured

created_at
required
string <date-time>

Timestamp when it was created

updated_at
required
string <date-time>

Timestamp when it was last updated

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/phone-numbers/did_01h2xcejqtf2nbrexx3vqjhp46 \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  • "phone_number": "+14155551234",
  • "status": "active",
  • "outbound_enabled": true,
  • "expires_at": null,
  • "disconnected_at": null,
  • "caller_id_name": "ACME Corp",
  • "directory_listing_name": "Acme Corporation",
  • "directory_listing_type": "listed",
  • "directory_listing_location_id": null,
  • "routing_target": null,
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

Update a phone number

Update properties of a phone number.

Authorizations:
BearerAuthSessionAuth
path Parameters
phone_number_id
required
string
Example: did_01h2xcejqtf2nbrexx3vqjhp46

Phone number identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
outbound_enabled
boolean

Whether this phone number can be used for outbound calling

status
string
Enum: "active" "inactive"

Set to inactive to stop routing inbound calls to this number, or active to resume routing. Setting to active on a released number triggers re-acquisition from the carrier; this fails with 409 if the number is no longer available.

expires_at
string or null <date-time>

Set to null to convert a temporary number into a permanent one (cancels the scheduled release). Extending the expiry is not supported.

directory_listing_name
string

Business name for the directory listing

directory_listing_type
string
Enum: "listed" "non_listed" "non_published" "non_registered"

How the number appears in directory services. Setting to a non-registered type removes any existing listing. Setting to listed, non_listed, or non_published submits a directory listing order.

directory_listing_location_id
string

ID of the location whose address to use for the listing. Required when directory_listing_type is not non_registered.

caller_id_name
string <= 15 characters

Caller ID (CNAM) display name. Max 15 ASCII characters per the CNAM standard. Submits an asynchronous order to the upstream provider. The phone number must be in active status.

caller_id_visibility
string
Default: "PUBLIC"
Enum: "PUBLIC" "PRIVATE"

Whether the caller ID name is publicly visible

Responses

Response Schema: application/json
id
required
string

Unique identifier

phone_number
required
string <= 20 characters

Phone number in E.164 format

status
required
string
Enum: "active" "inactive" "released"

Current status of the phone number

outbound_enabled
required
boolean

Whether this phone number can be used for outbound calling

expires_at
required
string or null <date-time>

When the phone number is scheduled to be released back to the carrier. Set on temporary numbers issued during signup; null on permanent numbers.

disconnected_at
required
string or null <date-time>

When the phone number was released back to the carrier. Null while the number is in service.

caller_id_name
string or null <= 15 characters

The caller ID name (CNAM) configured for this phone number, or null if not set

directory_listing_name
string or null

The business name used for directory listing (411/white pages), or null if not set

directory_listing_type
string
Enum: "listed" "non_listed" "non_published" "non_registered"

How the number appears in directory services

directory_listing_location_id
string or null

ID of the location whose address is published in the directory listing, or null

routing_target
required
string or null

ID of the target that inbound calls to this number are routed to, or null if no routing is configured

created_at
required
string <date-time>

Timestamp when it was created

updated_at
required
string <date-time>

Timestamp when it was last updated

Request samples

Content type
application/json
Example
{
  • "outbound_enabled": false
}

Response samples

Content type
application/json
{
  • "id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  • "phone_number": "+14155551234",
  • "status": "active",
  • "outbound_enabled": true,
  • "expires_at": null,
  • "disconnected_at": null,
  • "caller_id_name": "ACME Corp",
  • "directory_listing_name": "Acme Corporation",
  • "directory_listing_type": "listed",
  • "directory_listing_location_id": null,
  • "routing_target": null,
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

Search available phone numbers

Search for phone numbers available for purchase. At least one search filter is required: area_code, state, zip, npa_nxx, or city combined with state. Filters can be combined to narrow results.

Authorizations:
BearerAuthSessionAuth
query Parameters
area_code
string^\d{3}$
Example: area_code=919

Three-digit area code to search

city
string
Example: city=Raleigh

City name (requires state)

state
string^[A-Z]{2}$
Example: state=NC

Two-letter state abbreviation (can be used alone or with city)

zip
string^\d{5}$
Example: zip=27601

Five-digit US ZIP code

npa_nxx
string^\d{6}$
Example: npa_nxx=919555

Six-digit NPA-NXX prefix (area code + exchange)

quantity
integer [ 1 .. 100 ]
Default: 10

Number of results to return (1-100, default 10)

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
required
Array of objects (AvailablePhoneNumber)
Array
phone_number
required
string <= 20 characters

Phone number in E.164 format

city
string

City where the number is registered

state
string

Two-letter state abbreviation

rate_center
string

Rate center for the number

lata
string

Local access and transport area

Request samples 

curl -X GET \
  'https://api.dialstack.ai/v1/available-phone-numbers?area_code=919&city=Raleigh&state=NC&zip=27601&npa_nxx=919555&quantity=SOME_INTEGER_VALUE' \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
Example
{
  • "data": [
    ]
}

Order new phone numbers

Order one or more new phone numbers. Numbers must have been found via the search endpoint (GET /v1/available-phone-numbers). This endpoint is for acquiring new numbers only — it does not support porting existing numbers from another provider.

The order is created in pending status and typically completes within seconds. Poll the order via GET /v1/phone-number-orders/{order_id} or configure a webhook to be notified when it reaches a terminal status (complete, partial, or failed).

Authorizations:
BearerAuthSessionAuth
header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
phone_numbers
required
Array of strings [ 1 .. 100 ] items

Phone numbers to order (E.164 format)

partial_allowed
boolean
Default: false

When true, the order may partially complete — available numbers are provisioned and unavailable ones are marked as failed. When false (default), the entire order fails if any number is unavailable.

Responses

Response Schema: application/json
id
required
string

Unique identifier

order_type
required
string
Enum: "purchase" "disconnect"

purchase — acquire new phone numbers. disconnect — release existing phone numbers back to the provider.

status
required
string
Enum: "pending" "complete" "partial" "failed"

pending — order submitted, awaiting provider confirmation. complete — all requested numbers were successfully provisioned (or released). partial — some numbers succeeded, others failed. failed — the entire order was rejected.

phone_numbers
required
Array of strings

Phone numbers included in the order (E.164 format)

completed_numbers
required
Array of strings

Phone numbers that completed successfully

failed_numbers
required
Array of strings

Phone numbers that failed

error_message
string or null

Error details if the order failed

created_at
required
string <date-time>

Timestamp when it was created

updated_at
required
string <date-time>

Timestamp when it was last updated

Request samples

Content type
application/json
{
  • "phone_numbers": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  • "order_type": "purchase",
  • "status": "pending",
  • "phone_numbers": [
    ],
  • "completed_numbers": [
    ],
  • "failed_numbers": [ ],
  • "error_message": "string",
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

List phone number orders

Returns a paginated list of phone number orders for the account. Includes both purchase and disconnect orders. Results are returned in reverse chronological order (newest first).

Authorizations:
BearerAuthSessionAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

Number of objects to return. Defaults to 10. Maximum is 100.

status
string
Enum: "pending" "complete" "partial" "failed"

Filter by order status

order_type
string
Enum: "order" "disconnect"

Filter by order type

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
object
required
string (ListObject)
Value: "list"

String representing the object's type. Always "list" for list responses.

url
required
string (ListUrl)

The URL for accessing this list.

next_page_url
required
string or null (NextPageUrl)

URL to fetch the next page of results. If null, there are no more pages. The URL includes all necessary parameters including the pagination cursor.

previous_page_url
required
string or null (PreviousPageUrl)

URL to fetch the previous page of results. If null, this is the first page. The URL includes all necessary parameters including the pagination cursor.

required
Array of objects (NumberOrder)

Request samples 

curl -X GET \
  'https://api.dialstack.ai/v1/phone-number-orders?limit=10&status=SOME_STRING_VALUE&order_type=SOME_STRING_VALUE' \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "object": "list",
  • "url": "/v1/accounts",
  • "next_page_url": "/v1/accounts?page=eyJzdGFydGluZ19hZnRlciI6ImFjY3RfMDFoMnhjZWpxdGYybmJyZXh4M3ZxamhwNDEiLCJsaW1pdCI6MTB9",
  • "previous_page_url": "/v1/accounts?page=eyJlbmRpbmdfYmVmb3JlIjoiYWNjdF8wMWgyeGNlanF0ZjJuYnJleHgzdnFqaHA0MSIsImxpbWl0IjoxMH0",
  • "data": [
    ]
}

Get a phone number order

Retrieves a phone number order by ID. If the order is still pending, the status is refreshed from the provider before returning.

Authorizations:
BearerAuthSessionAuth
path Parameters
order_id
required
string
Example: nord_01h2xcejqtf2nbrexx3vqjhp47

Phone number order identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
id
required
string

Unique identifier

order_type
required
string
Enum: "purchase" "disconnect"

purchase — acquire new phone numbers. disconnect — release existing phone numbers back to the provider.

status
required
string
Enum: "pending" "complete" "partial" "failed"

pending — order submitted, awaiting provider confirmation. complete — all requested numbers were successfully provisioned (or released). partial — some numbers succeeded, others failed. failed — the entire order was rejected.

phone_numbers
required
Array of strings

Phone numbers included in the order (E.164 format)

completed_numbers
required
Array of strings

Phone numbers that completed successfully

failed_numbers
required
Array of strings

Phone numbers that failed

error_message
string or null

Error details if the order failed

created_at
required
string <date-time>

Timestamp when it was created

updated_at
required
string <date-time>

Timestamp when it was last updated

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/phone-number-orders/nord_01h2xcejqtf2nbrexx3vqjhp47 \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  • "order_type": "purchase",
  • "status": "pending",
  • "phone_numbers": [
    ],
  • "completed_numbers": [
    ],
  • "failed_numbers": [ ],
  • "error_message": "string",
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

Disconnect a phone number

Release a phone number back to the provider. Creates a disconnect order that transitions the phone number to released status on completion.

Authorizations:
BearerAuthSessionAuth
path Parameters
phone_number_id
required
string
Example: did_01h2xcejqtf2nbrexx3vqjhp46

Phone number identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
id
required
string

Unique identifier

order_type
required
string
Enum: "purchase" "disconnect"

purchase — acquire new phone numbers. disconnect — release existing phone numbers back to the provider.

status
required
string
Enum: "pending" "complete" "partial" "failed"

pending — order submitted, awaiting provider confirmation. complete — all requested numbers were successfully provisioned (or released). partial — some numbers succeeded, others failed. failed — the entire order was rejected.

phone_numbers
required
Array of strings

Phone numbers included in the order (E.164 format)

completed_numbers
required
Array of strings

Phone numbers that completed successfully

failed_numbers
required
Array of strings

Phone numbers that failed

error_message
string or null

Error details if the order failed

created_at
required
string <date-time>

Timestamp when it was created

updated_at
required
string <date-time>

Timestamp when it was last updated

Request samples 

curl -X POST \
  https://api.dialstack.ai/v1/phone-numbers/did_01h2xcejqtf2nbrexx3vqjhp46/disconnect \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  • "order_type": "purchase",
  • "status": "pending",
  • "phone_numbers": [
    ],
  • "completed_numbers": [
    ],
  • "failed_numbers": [ ],
  • "error_message": "string",
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

Reassign a phone number

Move a phone number to a different account.

On reassignment, the routing target is cleared and outbound calling is disabled. The phone number must be in active or inactive status.

Authorizations:
BearerAuthSessionAuth
path Parameters
phone_number_id
required
string
Example: did_01h2xcejqtf2nbrexx3vqjhp46

Phone number identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
target_account_id
required
string

ID of the account to reassign the phone number to

Responses

Response Schema: application/json
id
required
string

Unique identifier

phone_number
required
string <= 20 characters

Phone number in E.164 format

status
required
string
Enum: "active" "inactive" "released"

Current status of the phone number

outbound_enabled
required
boolean

Whether this phone number can be used for outbound calling

expires_at
required
string or null <date-time>

When the phone number is scheduled to be released back to the carrier. Set on temporary numbers issued during signup; null on permanent numbers.

disconnected_at
required
string or null <date-time>

When the phone number was released back to the carrier. Null while the number is in service.

caller_id_name
string or null <= 15 characters

The caller ID name (CNAM) configured for this phone number, or null if not set

directory_listing_name
string or null

The business name used for directory listing (411/white pages), or null if not set

directory_listing_type
string
Enum: "listed" "non_listed" "non_published" "non_registered"

How the number appears in directory services

directory_listing_location_id
string or null

ID of the location whose address is published in the directory listing, or null

routing_target
required
string or null

ID of the target that inbound calls to this number are routed to, or null if no routing is configured

created_at
required
string <date-time>

Timestamp when it was created

updated_at
required
string <date-time>

Timestamp when it was last updated

Request samples

Content type
application/json
{
  • "target_account_id": "acct_01h2xcejqtf2nbrexx3vqjhp47"
}

Response samples

Content type
application/json
{
  • "id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  • "phone_number": "+14155551234",
  • "status": "active",
  • "outbound_enabled": true,
  • "expires_at": null,
  • "disconnected_at": null,
  • "caller_id_name": "ACME Corp",
  • "directory_listing_name": "Acme Corporation",
  • "directory_listing_type": "listed",
  • "directory_listing_location_id": null,
  • "routing_target": null,
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

Update routing target

Set or clear the routing target for a phone number. The routing target determines where inbound calls to this number are directed.

Send a target ID to route calls to that target, or null to clear the current routing. Omitting the routing_target key returns the current phone number state unchanged.

Authorizations:
BearerAuthSessionAuth
path Parameters
phone_number_id
required
string
Example: did_01h2xcejqtf2nbrexx3vqjhp46

Phone number identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
routing_target
string or null

ID of the target to route inbound calls to, or null to clear routing

Responses

Response Schema: application/json
id
required
string

Unique identifier

phone_number
required
string <= 20 characters

Phone number in E.164 format

status
required
string
Enum: "active" "inactive" "released"

Current status of the phone number

outbound_enabled
required
boolean

Whether this phone number can be used for outbound calling

expires_at
required
string or null <date-time>

When the phone number is scheduled to be released back to the carrier. Set on temporary numbers issued during signup; null on permanent numbers.

disconnected_at
required
string or null <date-time>

When the phone number was released back to the carrier. Null while the number is in service.

caller_id_name
string or null <= 15 characters

The caller ID name (CNAM) configured for this phone number, or null if not set

directory_listing_name
string or null

The business name used for directory listing (411/white pages), or null if not set

directory_listing_type
string
Enum: "listed" "non_listed" "non_published" "non_registered"

How the number appears in directory services

directory_listing_location_id
string or null

ID of the location whose address is published in the directory listing, or null

routing_target
required
string or null

ID of the target that inbound calls to this number are routed to, or null if no routing is configured

created_at
required
string <date-time>

Timestamp when it was created

updated_at
required
string <date-time>

Timestamp when it was last updated

Request samples

Content type
application/json
Example
{
  • "routing_target": "user_01h2xcejqtf2nbrexx3vqjhp48"
}

Response samples

Content type
application/json
{
  • "id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  • "phone_number": "+14155551234",
  • "status": "active",
  • "outbound_enabled": true,
  • "expires_at": null,
  • "disconnected_at": null,
  • "caller_id_name": "ACME Corp",
  • "directory_listing_name": "Acme Corporation",
  • "directory_listing_type": "listed",
  • "directory_listing_location_id": null,
  • "routing_target": null,
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

Number Porting

Number porting (port-in) management. Transfer existing phone numbers from another carrier to DialStack. The eligibility check endpoint does not require the DialStack-Account header.

Check port-in eligibility

Check whether phone numbers are eligible for porting to DialStack. Returns carrier information for portable numbers and rate center details for non-portable numbers.

This is a pre-purchase check and does not require an account context.

Authorizations:
BearerAuthSessionAuth
Request Body schema: application/json
required
phone_numbers
required
Array of strings [ 1 .. 100 ] items

US phone numbers to check (E.164 format, no toll-free)

Responses

Response Schema: application/json
Array of objects (PortableNumber)

Numbers that can be ported

Array of objects (NonPortableNumber)

Numbers that cannot be ported

Request samples

Content type
application/json
{
  • "phone_numbers": [
    ]
}

Response samples

Content type
application/json
{
  • "portable_numbers": [
    ],
  • "non_portable_numbers": [
    ]
}

Create a draft port order

Create a new port order in draft status. After creating the draft, approve the order with an electronic signature, then submit it to begin the porting process.

Phone numbers are validated and normalized to E.164 format. Toll-free numbers are not supported.

Authorizations:
BearerAuthSessionAuth
header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
phone_numbers
required
Array of strings [ 1 .. 100 ] items

US phone numbers to port (E.164 format, no toll-free)

required
object (PortSubscriber)

Subscriber and authorization information for the port request

requested_foc_date
required
string <date>

Requested date for the port to complete (YYYY-MM-DD). Must be at least 5 business days and no more than 30 calendar days from today (excludes weekends and US federal holidays).

requested_foc_time
string

Requested time for the port to complete, in HH:MM format (08:00-20:00 Eastern). Optional.

Responses

Response Schema: application/json
id
required
string

Unique identifier

status
required
string
Enum: "draft" "approved" "submitted" "exception" "foc" "complete" "cancelled"

Current status of the port order

required
object (PortOrderDetails)

Details of the port order including phone numbers, subscriber information, and document metadata

submitted_at
string or null <date-time>

When the order was submitted for processing

created_at
required
string <date-time>

Timestamp when it was created

updated_at
required
string <date-time>

Timestamp when it was last updated

Request samples

Content type
application/json
{
  • "phone_numbers": [
    ],
  • "subscriber": {
    },
  • "requested_foc_date": "2026-03-01"
}

Response samples

Content type
application/json
{
  • "id": "por_01h2xcejqtf2nbrexx3vqjhp53",
  • "status": "draft",
  • "details": {
    },
  • "submitted_at": "2026-02-15T14:30:00Z",
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

List port orders

Returns a paginated list of port orders for the account. Results are returned in reverse chronological order (newest first). Optionally filter by status.

Authorizations:
BearerAuthSessionAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

Number of objects to return. Defaults to 10. Maximum is 100.

status
string
Enum: "draft" "approved" "submitted" "exception" "foc" "complete" "cancelled"

Filter by port order status

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
object
required
string (ListObject)
Value: "list"

String representing the object's type. Always "list" for list responses.

url
required
string (ListUrl)

The URL for accessing this list.

next_page_url
required
string or null (NextPageUrl)

URL to fetch the next page of results. If null, there are no more pages. The URL includes all necessary parameters including the pagination cursor.

previous_page_url
required
string or null (PreviousPageUrl)

URL to fetch the previous page of results. If null, this is the first page. The URL includes all necessary parameters including the pagination cursor.

required
Array of objects (PortOrder)

Request samples 

curl -X GET \
  'https://api.dialstack.ai/v1/port-orders?limit=10&status=SOME_STRING_VALUE' \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "object": "list",
  • "url": "/v1/accounts",
  • "next_page_url": "/v1/accounts?page=eyJzdGFydGluZ19hZnRlciI6ImFjY3RfMDFoMnhjZWpxdGYybmJyZXh4M3ZxamhwNDEiLCJsaW1pdCI6MTB9",
  • "previous_page_url": "/v1/accounts?page=eyJlbmRpbmdfYmVmb3JlIjoiYWNjdF8wMWgyeGNlanF0ZjJuYnJleHgzdnFqaHA0MSIsImxpbWl0IjoxMH0",
  • "data": [
    ]
}

Get a port order

Retrieve a port order by ID. If the order is in a non-terminal status (submitted, exception, or foc), the status is automatically refreshed from the carrier before returning.

Authorizations:
BearerAuthSessionAuth
path Parameters
order_id
required
string
Example: por_01h2xcejqtf2nbrexx3vqjhp53

Port order identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
id
required
string

Unique identifier

status
required
string
Enum: "draft" "approved" "submitted" "exception" "foc" "complete" "cancelled"

Current status of the port order

required
object (PortOrderDetails)

Details of the port order including phone numbers, subscriber information, and document metadata

submitted_at
string or null <date-time>

When the order was submitted for processing

created_at
required
string <date-time>

Timestamp when it was created

updated_at
required
string <date-time>

Timestamp when it was last updated

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/port-orders/por_01h2xcejqtf2nbrexx3vqjhp53 \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "id": "por_01h2xcejqtf2nbrexx3vqjhp53",
  • "status": "draft",
  • "details": {
    },
  • "submitted_at": "2026-02-15T14:30:00Z",
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

Update a port order

Update a port order that is in approved or exception status. Use this to correct information that caused a rejection, then resubmit. All fields are optional — only provided fields are updated. Updating an approved order clears the approval and reverts the status to draft.

Authorizations:
BearerAuthSessionAuth
path Parameters
order_id
required
string
Example: por_01h2xcejqtf2nbrexx3vqjhp53

Port order identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
phone_numbers
Array of strings [ 1 .. 100 ] items

Updated phone numbers (E.164 format, no toll-free)

object (PortSubscriber)

Subscriber and authorization information for the port request

requested_foc_date
string <date>

Updated requested completion date (YYYY-MM-DD). Must be at least 5 business days and no more than 30 calendar days from today.

requested_foc_time
string

Updated requested completion time in HH:MM format (08:00-20:00 Eastern)

resubmit
boolean
Default: false

When true and the order is in exception status, clears the rejection and re-submits to the carrier.

Responses

Response Schema: application/json
id
required
string

Unique identifier

status
required
string
Enum: "draft" "approved" "submitted" "exception" "foc" "complete" "cancelled"

Current status of the port order

required
object (PortOrderDetails)

Details of the port order including phone numbers, subscriber information, and document metadata

submitted_at
string or null <date-time>

When the order was submitted for processing

created_at
required
string <date-time>

Timestamp when it was created

updated_at
required
string <date-time>

Timestamp when it was last updated

Request samples

Content type
application/json
{
  • "subscriber": {
    }
}

Response samples

Content type
application/json
{
  • "id": "por_01h2xcejqtf2nbrexx3vqjhp53",
  • "status": "draft",
  • "details": {
    },
  • "submitted_at": "2026-02-15T14:30:00Z",
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

Submit a port order

Submit an approved port order for processing. The order must first be approved by the customer.

On success, the order status transitions from approved to submitted. The necessary authorization documents are generated and forwarded to the carrier automatically.

Authorizations:
BearerAuthSessionAuth
path Parameters
order_id
required
string
Example: por_01h2xcejqtf2nbrexx3vqjhp53

Port order identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
id
required
string

Unique identifier

status
required
string
Enum: "draft" "approved" "submitted" "exception" "foc" "complete" "cancelled"

Current status of the port order

required
object (PortOrderDetails)

Details of the port order including phone numbers, subscriber information, and document metadata

submitted_at
string or null <date-time>

When the order was submitted for processing

created_at
required
string <date-time>

Timestamp when it was created

updated_at
required
string <date-time>

Timestamp when it was last updated

Request samples 

curl -X POST \
  https://api.dialstack.ai/v1/port-orders/por_01h2xcejqtf2nbrexx3vqjhp53/submit \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "id": "por_01h2xcejqtf2nbrexx3vqjhp53",
  • "status": "draft",
  • "details": {
    },
  • "submitted_at": "2026-02-15T14:30:00Z",
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

Cancel a port order

Cancel a port order. Draft and approved orders are cancelled locally. Submitted orders are also cancelled with the carrier.

Cannot cancel orders in terminal status (complete or cancelled).

Authorizations:
BearerAuthSessionAuth
path Parameters
order_id
required
string
Example: por_01h2xcejqtf2nbrexx3vqjhp53

Port order identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
id
required
string

Unique identifier

status
required
string
Enum: "draft" "approved" "submitted" "exception" "foc" "complete" "cancelled"

Current status of the port order

required
object (PortOrderDetails)

Details of the port order including phone numbers, subscriber information, and document metadata

submitted_at
string or null <date-time>

When the order was submitted for processing

created_at
required
string <date-time>

Timestamp when it was created

updated_at
required
string <date-time>

Timestamp when it was last updated

Request samples 

curl -X POST \
  https://api.dialstack.ai/v1/port-orders/por_01h2xcejqtf2nbrexx3vqjhp53/cancel \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "id": "por_01h2xcejqtf2nbrexx3vqjhp53",
  • "status": "draft",
  • "details": {
    },
  • "submitted_at": "2026-02-15T14:30:00Z",
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

Approve a port order

Have the customer approve a port order by providing their electronic signature and IP address. This authorizes the number transfer and allows the order to be submitted.

The order must be in draft status and must have subscriber details.

On success, the order status transitions from draft to approved. If the order details are updated after approval, the approval is cleared and the status reverts to draft — the customer must approve again.

Authorizations:
BearerAuthSessionAuth
path Parameters
order_id
required
string
Example: por_01h2xcejqtf2nbrexx3vqjhp53

Port order identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
signature
required
string

Electronic signature (the customer's typed name authorizing the port)

ip
required
string

IP address of the customer approving the order

Responses

Response Schema: application/json
id
required
string

Unique identifier

status
required
string
Enum: "draft" "approved" "submitted" "exception" "foc" "complete" "cancelled"

Current status of the port order

required
object (PortOrderDetails)

Details of the port order including phone numbers, subscriber information, and document metadata

submitted_at
string or null <date-time>

When the order was submitted for processing

created_at
required
string <date-time>

Timestamp when it was created

updated_at
required
string <date-time>

Timestamp when it was last updated

Request samples

Content type
application/json
{
  • "signature": "Jane Smith",
  • "ip": "203.0.113.42"
}

Response samples

Content type
application/json
{
  • "id": "por_01h2xcejqtf2nbrexx3vqjhp53",
  • "status": "draft",
  • "details": {
    },
  • "submitted_at": "2026-02-15T14:30:00Z",
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

Upload CSR document

Upload an optional Customer Service Record (CSR) document for a port order. A CSR can help resolve porting issues by providing carrier account details.

Accepted formats: PDF, PNG, JPG, TIFF. Maximum file size: 3 MB.

Authorizations:
BearerAuthSessionAuth
path Parameters
order_id
required
string
Example: por_01h2xcejqtf2nbrexx3vqjhp53

Port order identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: multipart/form-data
required
file
required
string <binary>

CSR document file

Responses

Response Schema: application/json
message
string

Request samples 

curl -X POST \
  https://api.dialstack.ai/v1/port-orders/por_01h2xcejqtf2nbrexx3vqjhp53/csr \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41' \
  -H 'content-type: multipart/form-data' \
  --form file=string

Response samples

Content type
application/json
{
  • "message": "csr uploaded successfully"
}

Download CSR document

Download the Customer Service Record (CSR) document for a port order.

Authorizations:
BearerAuthSessionAuth
path Parameters
order_id
required
string
Example: por_01h2xcejqtf2nbrexx3vqjhp53

Port order identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema:
string <binary>

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/port-orders/por_01h2xcejqtf2nbrexx3vqjhp53/csr \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "error": "Invalid request body",
  • "code": "validation_error",
  • "details": { }
}

Upload bill copy document

Upload an optional bill copy document for a port order. A bill copy can help resolve porting issues by providing carrier account details.

Accepted formats: PDF, PNG, JPG, TIFF. Maximum file size: 3 MB.

Authorizations:
BearerAuthSessionAuth
path Parameters
order_id
required
string
Example: por_01h2xcejqtf2nbrexx3vqjhp53

Port order identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: multipart/form-data
required
file
required
string <binary>

Bill copy document file

Responses

Response Schema: application/json
message
string

Request samples 

curl -X POST \
  https://api.dialstack.ai/v1/port-orders/por_01h2xcejqtf2nbrexx3vqjhp53/bill-copy \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41' \
  -H 'content-type: multipart/form-data' \
  --form file=string

Response samples

Content type
application/json
{
  • "message": "bill_copy uploaded successfully"
}

Download bill copy document

Download the bill copy document for a port order.

Authorizations:
BearerAuthSessionAuth
path Parameters
order_id
required
string
Example: por_01h2xcejqtf2nbrexx3vqjhp53

Port order identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema:
string <binary>

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/port-orders/por_01h2xcejqtf2nbrexx3vqjhp53/bill-copy \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "error": "Invalid request body",
  • "code": "validation_error",
  • "details": { }
}

List port order events

Returns the audit trail of status changes for a port order, in reverse chronological order.

Authorizations:
BearerAuthSessionAuth
path Parameters
order_id
required
string
Example: por_01h2xcejqtf2nbrexx3vqjhp53

Port order identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
object
required
string (ListObject)
Value: "list"

String representing the object's type. Always "list" for list responses.

required
Array of objects (PortOrderEvent)

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/port-orders/por_01h2xcejqtf2nbrexx3vqjhp53/events \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "object": "list",
  • "data": [
    ]
}

Locations

Business location management. Locations represent physical offices or business premises with validated addresses. Requires account context via DialStack-Account header or session token.

Create a location

Create a new business location with a validated address.

Authorizations:
BearerAuthSessionAuth
header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
name
required
string <= 255 characters

Display name of the location

required
object (AddressInput)

Address fields for creating or updating a location

primary_did_id
string

ID of the primary phone number for this location

Responses

Response Schema: application/json
id
required
string

Unique identifier

name
required
string <= 255 characters

Display name of the location

required
object (Address)

A validated, normalized physical address (embedded value object)

primary_did_id
string or null

The primary phone number assigned to this location

status
required
string
Enum: "active" "inactive"

Operational status of the location

e911_status
required
string
Enum: "none" "pending" "binding" "provisioned" "failed"

E911 provisioning status for this location. Managed by the provider; read-only.

object (LocationConfig)

Per-location configuration overrides

created_at
required
string <date-time>

Timestamp when it was created

updated_at
required
string <date-time>

Timestamp when it was last updated

Request samples

Content type
application/json
{
  • "name": "Main Office",
  • "address": {
    }
}

Response samples

Content type
application/json
{
  • "id": "loc_01h2xcejqtf2nbrexx3vqjhp50",
  • "name": "Main Office",
  • "address": {
    },
  • "status": "active",
  • "e911_status": "none",
  • "created_at": "2025-10-18T10:00:00Z",
  • "updated_at": "2025-10-18T10:00:00Z"
}

List locations

List all locations for the account. Results are returned in reverse chronological order (newest first).

Authorizations:
BearerAuthSessionAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

Number of objects to return. Defaults to 10. Maximum is 100.

status
string
Enum: "active" "inactive"
Example: status=active

Filter by location status

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
object
required
string (ListObject)
Value: "list"

String representing the object's type. Always "list" for list responses.

url
required
string (ListUrl)

The URL for accessing this list.

next_page_url
required
string or null (NextPageUrl)

URL to fetch the next page of results. If null, there are no more pages. The URL includes all necessary parameters including the pagination cursor.

previous_page_url
required
string or null (PreviousPageUrl)

URL to fetch the previous page of results. If null, this is the first page. The URL includes all necessary parameters including the pagination cursor.

required
Array of objects (Location)

Request samples 

curl -X GET \
  'https://api.dialstack.ai/v1/locations?limit=10&status=active' \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "object": "list",
  • "url": "/v1/locations",
  • "next_page_url": null,
  • "previous_page_url": null,
  • "data": [
    ]
}

Get location details

Retrieve a specific location by ID.

Authorizations:
BearerAuthSessionAuth
path Parameters
location_id
required
string
Example: loc_01h2xcejqtf2nbrexx3vqjhp50

Location identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
id
required
string

Unique identifier

name
required
string <= 255 characters

Display name of the location

required
object (Address)

A validated, normalized physical address (embedded value object)

primary_did_id
string or null

The primary phone number assigned to this location

status
required
string
Enum: "active" "inactive"

Operational status of the location

e911_status
required
string
Enum: "none" "pending" "binding" "provisioned" "failed"

E911 provisioning status for this location. Managed by the provider; read-only.

object (LocationConfig)

Per-location configuration overrides

created_at
required
string <date-time>

Timestamp when it was created

updated_at
required
string <date-time>

Timestamp when it was last updated

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/locations/loc_01h2xcejqtf2nbrexx3vqjhp50 \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  • "name": "Main Office",
  • "address": {
    },
  • "primary_did_id": "string",
  • "status": "active",
  • "e911_status": "none",
  • "config": {
    },
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

Update location

Update location details (name, address, primary phone number, or status).

Authorizations:
BearerAuthSessionAuth
path Parameters
location_id
required
string
Example: loc_01h2xcejqtf2nbrexx3vqjhp50

Location identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
name
string <= 255 characters

Display name of the location

object (AddressInput)

Address fields for creating or updating a location

primary_did_id
string

ID of the primary phone number for this location

status
string
Enum: "active" "inactive"

Operational status of the location

object (LocationConfig)

Per-location configuration overrides

Responses

Response Schema: application/json
id
required
string

Unique identifier

name
required
string <= 255 characters

Display name of the location

required
object (Address)

A validated, normalized physical address (embedded value object)

primary_did_id
string or null

The primary phone number assigned to this location

status
required
string
Enum: "active" "inactive"

Operational status of the location

e911_status
required
string
Enum: "none" "pending" "binding" "provisioned" "failed"

E911 provisioning status for this location. Managed by the provider; read-only.

object (LocationConfig)

Per-location configuration overrides

created_at
required
string <date-time>

Timestamp when it was created

updated_at
required
string <date-time>

Timestamp when it was last updated

Request samples

Content type
application/json
{
  • "name": "Updated Office",
  • "address": {
    },
  • "primary_did_id": "string",
  • "status": "active",
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  • "name": "Main Office",
  • "address": {
    },
  • "primary_did_id": "string",
  • "status": "active",
  • "e911_status": "none",
  • "config": {
    },
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

Delete location

Delete a location and its associated address. This operation is irreversible.

Authorizations:
BearerAuthSessionAuth
path Parameters
location_id
required
string
Example: loc_01h2xcejqtf2nbrexx3vqjhp50

Location identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Request samples 

curl -X DELETE \
  https://api.dialstack.ai/v1/locations/loc_01h2xcejqtf2nbrexx3vqjhp50 \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "error": "Invalid request body",
  • "code": "validation_error",
  • "details": { }
}

Validate E911 address

Pre-check the location's address for E911 provisioning. Returns the address fields that will be used during provisioning. Full address validation occurs during the provision-e911 call.

Authorizations:
BearerAuthSessionAuth
path Parameters
location_id
required
string
Example: loc_01h2xcejqtf2nbrexx3vqjhp50

Location identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
adjusted
required
boolean

Whether the address was adjusted during geocoding

object

The geocoded address used for E911 registration

Request samples 

curl -X POST \
  https://api.dialstack.ai/v1/locations/loc_01h2xcejqtf2nbrexx3vqjhp50/validate-e911 \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "adjusted": true,
  • "address": {
    }
}

Provision E911

Start E911 provisioning for a location. The location must have a primary phone number assigned. Provisioning is asynchronous; the e911_status field tracks progress.

Authorizations:
BearerAuthSessionAuth
path Parameters
location_id
required
string
Example: loc_01h2xcejqtf2nbrexx3vqjhp50

Location identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
id
required
string

Unique identifier

name
required
string <= 255 characters

Display name of the location

required
object (Address)

A validated, normalized physical address (embedded value object)

primary_did_id
string or null

The primary phone number assigned to this location

status
required
string
Enum: "active" "inactive"

Operational status of the location

e911_status
required
string
Enum: "none" "pending" "binding" "provisioned" "failed"

E911 provisioning status for this location. Managed by the provider; read-only.

object (LocationConfig)

Per-location configuration overrides

created_at
required
string <date-time>

Timestamp when it was created

updated_at
required
string <date-time>

Timestamp when it was last updated

Request samples 

curl -X POST \
  https://api.dialstack.ai/v1/locations/loc_01h2xcejqtf2nbrexx3vqjhp50/provision-e911 \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  • "name": "Main Office",
  • "address": {
    },
  • "primary_did_id": "string",
  • "status": "active",
  • "e911_status": "none",
  • "config": {
    },
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

AI Agents

AI-powered voice agent management. AI agents provide automated call handling with customizable instructions and FAQ responses. Each agent automatically manages a voice app and extension for call routing. Requires account context via DialStack-Account header.

Create an AI agent

Create a new AI agent within the account. This automatically provisions a managed voice app and extension for call routing.

Authorizations:
BearerAuthSessionAuth
header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
name
required
string [ 1 .. 255 ] characters

Display name for the AI agent

extension_number
string

Extension number to assign for routing calls to this agent

persona_name
string or null <= 255 characters

The name the AI agent uses to introduce itself on calls

greeting_name
string or null <= 255 characters

The business name used in call greetings (e.g. "Thanks for calling [Greeting Name]"). When not set, the account name is used as a fallback.

instructions
string or null <= 10000 characters

Custom instructions for the AI agent's behavior

Array of objects (FAQItem)

Pre-configured question-answer pairs

object (SchedulingConfig)

Scheduling webhook configuration. Scheduling is on when webhook_url is provided, off when absent or empty. DialStack appends standard paths to the base URL for each operation. This is a replace-all object — send the complete configuration on every update.

Responses

Response Schema: application/json
id
required
string

Unique identifier

name
required
string or null [ 1 .. 255 ] characters

Display name

voice_app_id
required
string

The managed voice app used for call routing

persona_name
string or null <= 255 characters

The name the AI agent uses to introduce itself on calls (e.g. "Tony"). Defaults to "the receptionist" if not set.

greeting_name
string or null <= 255 characters

The business name used in call greetings (e.g. "Thanks for calling [Greeting Name]"). When not set, the account name is used as a fallback.

instructions
string or null <= 10000 characters

Custom instructions for the AI agent's behavior

required
Array of objects (FAQItem)

Pre-configured question-answer pairs

object (SchedulingConfig)

Scheduling webhook configuration. Scheduling is on when webhook_url is provided, off when absent or empty. DialStack appends standard paths to the base URL for each operation. This is a replace-all object — send the complete configuration on every update.

created_at
required
string <date-time> (CreatedAt)

Timestamp when it was created

updated_at
required
string <date-time> (UpdatedAt)

Timestamp when it was last updated

Request samples

Content type
application/json
{
  • "name": "Front Desk Receptionist",
  • "extension_number": "200",
  • "instructions": "You are the receptionist for Jones Family Dental.",
  • "faq_responses": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "aia_01h2xcejqtf2nbrexx3vqjhp60",
  • "name": "Front Desk Receptionist",
  • "voice_app_id": "va_01h2xcejqtf2nbrexx3vqjhp49",
  • "persona_name": "Tony",
  • "greeting_name": "Jones Family Dental",
  • "instructions": "You are the receptionist for Jones Family Dental. Be warm and professional.",
  • "faq_responses": [
    ],
  • "scheduling": {},
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

List AI agents

List all AI agents for the account. Results are returned in reverse chronological order (newest first).

Authorizations:
BearerAuthSessionAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

Number of objects to return. Defaults to 10. Maximum is 100.

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
object
required
string (ListObject)
Value: "list"

String representing the object's type. Always "list" for list responses.

url
required
string (ListUrl)

The URL for accessing this list.

next_page_url
required
string or null (NextPageUrl)

URL to fetch the next page of results. If null, there are no more pages. The URL includes all necessary parameters including the pagination cursor.

previous_page_url
required
string or null (PreviousPageUrl)

URL to fetch the previous page of results. If null, this is the first page. The URL includes all necessary parameters including the pagination cursor.

required
Array of objects (AIAgent)

Request samples 

curl -X GET \
  'https://api.dialstack.ai/v1/ai-agents?limit=10' \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "object": "list",
  • "url": "/v1/accounts",
  • "next_page_url": "/v1/accounts?page=eyJzdGFydGluZ19hZnRlciI6ImFjY3RfMDFoMnhjZWpxdGYybmJyZXh4M3ZxamhwNDEiLCJsaW1pdCI6MTB9",
  • "previous_page_url": "/v1/accounts?page=eyJlbmRpbmdfYmVmb3JlIjoiYWNjdF8wMWgyeGNlanF0ZjJuYnJleHgzdnFqaHA0MSIsImxpbWl0IjoxMH0",
  • "data": [
    ]
}

Get AI agent details

Retrieve a specific AI agent by ID.

Authorizations:
BearerAuthSessionAuth
path Parameters
ai_agent_id
required
string
Example: aia_01h2xcejqtf2nbrexx3vqjhp60

AI agent identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
id
required
string

Unique identifier

name
required
string or null [ 1 .. 255 ] characters

Display name

voice_app_id
required
string

The managed voice app used for call routing

persona_name
string or null <= 255 characters

The name the AI agent uses to introduce itself on calls (e.g. "Tony"). Defaults to "the receptionist" if not set.

greeting_name
string or null <= 255 characters

The business name used in call greetings (e.g. "Thanks for calling [Greeting Name]"). When not set, the account name is used as a fallback.

instructions
string or null <= 10000 characters

Custom instructions for the AI agent's behavior

required
Array of objects (FAQItem)

Pre-configured question-answer pairs

object (SchedulingConfig)

Scheduling webhook configuration. Scheduling is on when webhook_url is provided, off when absent or empty. DialStack appends standard paths to the base URL for each operation. This is a replace-all object — send the complete configuration on every update.

created_at
required
string <date-time> (CreatedAt)

Timestamp when it was created

updated_at
required
string <date-time> (UpdatedAt)

Timestamp when it was last updated

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/ai-agents/aia_01h2xcejqtf2nbrexx3vqjhp60 \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "id": "aia_01h2xcejqtf2nbrexx3vqjhp60",
  • "name": "Front Desk Receptionist",
  • "voice_app_id": "va_01h2xcejqtf2nbrexx3vqjhp49",
  • "persona_name": "Tony",
  • "greeting_name": "Jones Family Dental",
  • "instructions": "You are the receptionist for Jones Family Dental. Be warm and professional.",
  • "faq_responses": [
    ],
  • "scheduling": {},
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

Update AI agent

Update AI agent details (name, instructions, or FAQ responses).

Authorizations:
BearerAuthSessionAuth
path Parameters
ai_agent_id
required
string
Example: aia_01h2xcejqtf2nbrexx3vqjhp60

AI agent identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
name
string [ 1 .. 255 ] characters

Display name for the AI agent

persona_name
string or null <= 255 characters

The name the AI agent uses to introduce itself on calls

greeting_name
string or null <= 255 characters

The business name used in call greetings (e.g. "Thanks for calling [Greeting Name]"). When not set, the account name is used as a fallback.

instructions
string or null <= 10000 characters

Custom instructions for the AI agent's behavior

Array of objects (FAQItem)

Pre-configured question-answer pairs (replaces all existing items)

object (SchedulingConfig)

Scheduling configuration. Replaces the entire scheduling object (not merged field-by-field). Omit entirely to leave unchanged.

Responses

Response Schema: application/json
id
required
string

Unique identifier

name
required
string or null [ 1 .. 255 ] characters

Display name

voice_app_id
required
string

The managed voice app used for call routing

persona_name
string or null <= 255 characters

The name the AI agent uses to introduce itself on calls (e.g. "Tony"). Defaults to "the receptionist" if not set.

greeting_name
string or null <= 255 characters

The business name used in call greetings (e.g. "Thanks for calling [Greeting Name]"). When not set, the account name is used as a fallback.

instructions
string or null <= 10000 characters

Custom instructions for the AI agent's behavior

required
Array of objects (FAQItem)

Pre-configured question-answer pairs

object (SchedulingConfig)

Scheduling webhook configuration. Scheduling is on when webhook_url is provided, off when absent or empty. DialStack appends standard paths to the base URL for each operation. This is a replace-all object — send the complete configuration on every update.

created_at
required
string <date-time> (CreatedAt)

Timestamp when it was created

updated_at
required
string <date-time> (UpdatedAt)

Timestamp when it was last updated

Request samples

Content type
application/json
{
  • "name": "Updated Receptionist",
  • "persona_name": "Tony",
  • "greeting_name": "Jones Family Dental",
  • "instructions": "string",
  • "faq_responses": [
    ],
  • "scheduling": {}
}

Response samples

Content type
application/json
{
  • "id": "aia_01h2xcejqtf2nbrexx3vqjhp60",
  • "name": "Front Desk Receptionist",
  • "voice_app_id": "va_01h2xcejqtf2nbrexx3vqjhp49",
  • "persona_name": "Tony",
  • "greeting_name": "Jones Family Dental",
  • "instructions": "You are the receptionist for Jones Family Dental. Be warm and professional.",
  • "faq_responses": [
    ],
  • "scheduling": {},
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

Delete AI agent

Delete an AI agent and its managed voice app and extension. This operation is irreversible.

Authorizations:
BearerAuthSessionAuth
path Parameters
ai_agent_id
required
string
Example: aia_01h2xcejqtf2nbrexx3vqjhp60

AI agent identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Request samples 

curl -X DELETE \
  https://api.dialstack.ai/v1/ai-agents/aia_01h2xcejqtf2nbrexx3vqjhp60 \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "error": "Invalid request body",
  • "code": "validation_error",
  • "details": { }
}

Voice Apps

Voice app management for programmable voice applications. Voice apps handle calls via HTTP webhook notification and optional WebSocket audio streaming. Requires account context via DialStack-Account header.

Create a voice app

Create a new voice app within the account. Voice apps handle calls via HTTP webhook notification and optional WebSocket audio streaming.

Authorizations:
BearerAuthSessionAuth
header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
name
required
string or null (EntityName) [ 1 .. 255 ] characters

Display name

url
required
string <uri>

HTTPS webhook URL for call control notifications

Responses

Response Schema: application/json
id
required
string

Unique identifier

name
required
string or null [ 1 .. 255 ] characters

Display name

url
required
string <uri>

HTTPS webhook URL for call control notifications

status
required
string
Enum: "active" "inactive"

Current status of the voice app

secret
required
string

Webhook signing secret for this voice app. Used to verify webhook signatures.

created_at
required
string <date-time>

Timestamp when it was created

updated_at
string <date-time>

Timestamp when it was last updated

object

List of extensions assigned to this voice app. Only included when expand[]=extensions is requested.

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "va_01h2xcejqtf2nbrexx3vqjhp49",
  • "name": "AI Receptionist",
  • "url": "https://ai.platform.example.com/calls",
  • "status": "active",
  • "secret": "whsec_abc123def456...",
  • "created_at": "2025-10-18T10:00:00Z",
  • "updated_at": "2025-10-18T10:00:00Z"
}

List voice apps

List all voice apps for the account. Results are returned in reverse chronological order (newest first).

Authorizations:
BearerAuthSessionAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

Number of objects to return. Defaults to 10. Maximum is 100.

expand[]
Array of strings
Items Value: "extensions"

Related resources to include inline. Supported values: extensions.

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
object
required
string (ListObject)
Value: "list"

String representing the object's type. Always "list" for list responses.

url
required
string (ListUrl)

The URL for accessing this list.

next_page_url
required
string or null (NextPageUrl)

URL to fetch the next page of results. If null, there are no more pages. The URL includes all necessary parameters including the pagination cursor.

previous_page_url
required
string or null (PreviousPageUrl)

URL to fetch the previous page of results. If null, this is the first page. The URL includes all necessary parameters including the pagination cursor.

required
Array of objects (VoiceApp)

Request samples 

curl -X GET \
  'https://api.dialstack.ai/v1/voice-apps?limit=10&expand%5B%5D=SOME_ARRAY_VALUE' \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "object": "list",
  • "url": "/v1/voice-apps",
  • "next_page_url": null,
  • "previous_page_url": null,
  • "data": [
    ]
}

Get voice app details

Retrieve a specific voice app by ID.

Authorizations:
BearerAuthSessionAuth
path Parameters
voice_app_id
required
string
Example: va_01h2xcejqtf2nbrexx3vqjhp49

Voice app identifier

query Parameters
expand[]
Array of strings
Items Value: "extensions"

Related resources to include inline. Supported values: extensions.

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
id
required
string

Unique identifier

name
required
string or null [ 1 .. 255 ] characters

Display name

url
required
string <uri>

HTTPS webhook URL for call control notifications

status
required
string
Enum: "active" "inactive"

Current status of the voice app

secret
required
string

Webhook signing secret for this voice app. Used to verify webhook signatures.

created_at
required
string <date-time>

Timestamp when it was created

updated_at
string <date-time>

Timestamp when it was last updated

object

List of extensions assigned to this voice app. Only included when expand[]=extensions is requested.

Request samples 

curl -X GET \
  'https://api.dialstack.ai/v1/voice-apps/va_01h2xcejqtf2nbrexx3vqjhp49?expand%5B%5D=SOME_ARRAY_VALUE' \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "id": "va_01h2xcejqtf2nbrexx3vqjhp49",
  • "name": "AI Receptionist",
  • "url": "https://ai.platform.example.com/calls",
  • "status": "active",
  • "secret": "whsec_abc123def456...",
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z",
  • "extensions": {
    }
}

Update voice app

Update voice app details (name, URL, or status).

Authorizations:
BearerAuthSessionAuth
path Parameters
voice_app_id
required
string
Example: va_01h2xcejqtf2nbrexx3vqjhp49

Voice app identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
name
string or null (EntityName) [ 1 .. 255 ] characters

Display name

url
string <uri>

HTTPS webhook URL for call control notifications

status
string
Enum: "active" "inactive"

Voice app status

Responses

Response Schema: application/json
id
required
string

Unique identifier

name
required
string or null [ 1 .. 255 ] characters

Display name

url
required
string <uri>

HTTPS webhook URL for call control notifications

status
required
string
Enum: "active" "inactive"

Current status of the voice app

secret
required
string

Webhook signing secret for this voice app. Used to verify webhook signatures.

created_at
required
string <date-time>

Timestamp when it was created

updated_at
string <date-time>

Timestamp when it was last updated

object

List of extensions assigned to this voice app. Only included when expand[]=extensions is requested.

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "va_01h2xcejqtf2nbrexx3vqjhp49",
  • "name": "AI Receptionist",
  • "url": "https://ai.platform.example.com/calls",
  • "status": "active",
  • "secret": "whsec_abc123def456...",
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z",
  • "extensions": {
    }
}

Delete voice app

Delete a voice app. Active calls to this voice app will be terminated. This operation is irreversible.

Authorizations:
BearerAuthSessionAuth
path Parameters
voice_app_id
required
string
Example: va_01h2xcejqtf2nbrexx3vqjhp49

Voice app identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Request samples 

curl -X DELETE \
  https://api.dialstack.ai/v1/voice-apps/va_01h2xcejqtf2nbrexx3vqjhp49 \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "error": "Invalid request body",
  • "code": "validation_error",
  • "details": { }
}

Rotate webhook secret

Generate a new webhook signing secret for the voice app. The old secret is immediately invalidated.

Authorizations:
BearerAuthSessionAuth
path Parameters
voice_app_id
required
string
Example: va_01h2xcejqtf2nbrexx3vqjhp49

Voice app identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
id
required
string

Unique identifier

name
required
string or null [ 1 .. 255 ] characters

Display name

url
required
string <uri>

HTTPS webhook URL for call control notifications

status
required
string
Enum: "active" "inactive"

Current status of the voice app

secret
required
string

Webhook signing secret for this voice app. Used to verify webhook signatures.

created_at
required
string <date-time>

Timestamp when it was created

updated_at
string <date-time>

Timestamp when it was last updated

object

List of extensions assigned to this voice app. Only included when expand[]=extensions is requested.

Request samples 

curl -X POST \
  https://api.dialstack.ai/v1/voice-apps/va_01h2xcejqtf2nbrexx3vqjhp49/rotate_secret \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "id": "va_01h2xcejqtf2nbrexx3vqjhp49",
  • "name": "AI Receptionist",
  • "url": "https://ai.platform.example.com/calls",
  • "status": "active",
  • "secret": "whsec_abc123def456...",
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z",
  • "extensions": {
    }
}

Devices

Unified device API for deskphones, DECT bases, and DECT handsets. This is the recommended way to manage devices. Use /v1/devices to create, list, get, and delete any device type, and /v1/devices/{id}/users to assign and manage users on any device type.

The type-specific /v1/deskphones and /v1/dect-bases endpoints are retained only for operations that have no unified equivalent yet (updates, provisioning-events, listing handsets under a specific base). Prefer /v1/devices everywhere else.

Requires account context via DialStack-Account header or session token.

Create a device

Recommended way to create any device. Prefer this endpoint over POST /v1/deskphones, POST /v1/dect-bases, and POST /v1/dect-bases/{id}/handsets.

Supported types:

  • deskphone requires mac_address
  • dect_base requires mac_address
  • dect_handset requires ipei. base_id is optional — omit to stock the handset as unpaired and pair it later.
Authorizations:
BearerAuthSessionAuth
header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
type
required
string
Enum: "deskphone" "dect_base" "dect_handset"

The kind of device to create

mac_address
string

Hardware MAC address (required for deskphones and DECT bases)

model
string

Device model (optional)

name
string

Human-friendly label for the device (deskphone, DECT base, or DECT handset).

object or null (DeviceSettings)

Two-tier device settings with vendor-agnostic abstractions and vendor-specific overrides. All fields are optional — omitted fields inherit from the parent configuration layer (Global defaults → Platform → Account → Device).

This schema evolves as new hardware capabilities are supported. The vendor_overrides field provides an escape hatch for vendor-specific parameters not yet covered by abstractions.

multicell_role
string
Enum: "single" "data_master" "secondary"

Multicell deployment role (DECT base only, defaults to single)

location_id
string

Physical E911 location to assign at creation (deskphone or DECT base only). Can be set later via update.

base_id
string

Parent DECT base identifier (DECT handset only). Optional — omit to stock the handset as unpaired; pair it later by updating the handset with a base_id.

ipei
string

DECT handset IPEI (required for DECT handsets)

display_name
string
Deprecated

Deprecated alias of name for DECT handset creates. Send name instead. If both are present, name wins.

Responses

Response Schema: application/json
id
required
string

Unique identifier

type
required
string
Enum: "deskphone" "dect_base" "dect_handset"

The kind of device that was created

Request samples

Content type
application/json
Example
{
  • "type": "deskphone",
  • "mac_address": "00:04:13:aa:bb:cc",
  • "model": "D785"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "deskphone"
}

List devices

Recommended way to list devices. Prefer this endpoint over GET /v1/deskphones and GET /v1/dect-bases.

Unified view of devices (deskphones, DECT base stations, and DECT handsets). Use the optional type filter to return only one device type. Use expand[]=users to include device/user assignment metadata. Results are returned in reverse chronological order (newest first).

Authorizations:
BearerAuthSessionAuth
query Parameters
type
string
Enum: "deskphone" "dect_base" "dect_handset"

Filter devices by type

limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

Number of objects to return. Defaults to 10. Maximum is 100.

expand[]
Array of strings
Items Value: "users"

Related resources to include inline. Supported values: users.

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
object
required
string (ListObject)
Value: "list"

String representing the object's type. Always "list" for list responses.

url
required
string (ListUrl)

The URL for accessing this list.

next_page_url
required
string or null (NextPageUrl)

URL to fetch the next page of results. If null, there are no more pages. The URL includes all necessary parameters including the pagination cursor.

previous_page_url
required
string or null (PreviousPageUrl)

URL to fetch the previous page of results. If null, this is the first page. The URL includes all necessary parameters including the pagination cursor.

required
Array of objects (Device)

Request samples 

curl -X GET \
  'https://api.dialstack.ai/v1/devices?type=SOME_STRING_VALUE&limit=10&expand%5B%5D=SOME_ARRAY_VALUE' \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "object": "list",
  • "url": "/v1/accounts",
  • "next_page_url": "/v1/accounts?page=eyJzdGFydGluZ19hZnRlciI6ImFjY3RfMDFoMnhjZWpxdGYybmJyZXh4M3ZxamhwNDEiLCJsaW1pdCI6MTB9",
  • "previous_page_url": "/v1/accounts?page=eyJlbmRpbmdfYmVmb3JlIjoiYWNjdF8wMWgyeGNlanF0ZjJuYnJleHgzdnFqaHA0MSIsImxpbWl0IjoxMH0",
  • "data": [
    ]
}

Get a device

Recommended way to fetch any device. Prefer this endpoint over GET /v1/deskphones/{id}, GET /v1/dect-bases/{id}, and GET /v1/dect-bases/{id}/handsets/{handset_id}.

Unified view of a single device. Works for deskphones, DECT base stations, and DECT handsets.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string

Device identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
id
required
string

Unique identifier

type
required
string
Enum: "deskphone" "dect_base" "dect_handset"

The kind of device

mac_address
required
string

Hardware MAC address

vendor
required
string

Device vendor (auto-detected from MAC address)

model
string or null

Device model

name
string or null

Human-friendly label for the device. Set by admins on deskphones, DECT bases, and DECT handsets; null when unassigned. Handset responses also expose this value as display_name for backwards compatibility with older clients.

location_id
string or null

Physical E911 location for this device. Set on deskphones and DECT bases; null when unassigned. DECT handsets have no location_id of their own — they inherit from the paired base and the handset response carries null here. See the E911 guide for the dispatch resolution rules.

status
required
string
Enum: "pending-sync" "provisioned"

Current provisioning status

object or null

Device-specific settings overrides

current_ip_address
string or null

Last known IP address of the device

last_provisioned_at
string or null <date-time>

When the device last fetched its configuration

created_at
required
string <date-time> (CreatedAt)

Timestamp when it was created

updated_at
required
string <date-time> (UpdatedAt)

Timestamp when it was last updated

primary_line_id
string or null

Primary SIP line (deskphone only)

Array of objects (DeviceLine)

SIP line assignments (deskphone only)

multicell_role
string or null
Enum: "single" "data_master" "secondary" null

Role in a multicell deployment (DECT base only)

max_handsets
integer or null

Maximum number of handsets supported (DECT base only)

firmware_version
string or null

Current firmware version (DECT bases and handsets)

Array of objects (DECTHandset)

Paired handsets (DECT base only)

base_id
string or null

Parent DECT base station (DECT handset only)

ipei
string or null

DECT handset IPEI (DECT handset only)

display_name
string or null

Optional display name (DECT handset only)

slot_number
integer or null

Slot number on the base station (DECT handset only)

registered_at
string or null <date-time>

When the handset registered with the base (DECT handset only)

Array of objects (HandsetLine)

SIP line assignments on this handset (DECT handset only)

Array of objects (DeviceUserAssignment)

User assignments. Only included when expand[]=users is requested.

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/devices/%7Bid%7D \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "deskphone",
  • "mac_address": "00:04:13:aa:bb:cc",
  • "vendor": "snom",
  • "model": "D785",
  • "name": "string",
  • "location_id": "string",
  • "status": "pending-sync",
  • "overrides": {
    },
  • "current_ip_address": "192.168.1.100",
  • "last_provisioned_at": "2019-08-24T14:15:22Z",
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z",
  • "primary_line_id": "string",
  • "lines": [
    ],
  • "multicell_role": "single",
  • "max_handsets": 30,
  • "firmware_version": "string",
  • "handsets": [
    ],
  • "base_id": "string",
  • "ipei": "string",
  • "display_name": "string",
  • "slot_number": 0,
  • "registered_at": "2019-08-24T14:15:22Z",
  • "extensions": [
    ],
  • "assignments": [
    ]
}

Update a device

Update a device by ID. Works for deskphones, DECT base stations, and DECT handsets. DECT handset updates support name, ipei, and model.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string

Device identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
model
string

Device model

name
string or null

Human-friendly label for the device (deskphone, DECT base, or DECT handset). Send null to clear.

status
string
Enum: "pending-sync" "provisioned"

Provisioning status for deskphones and DECT bases

object or null (DeviceSettings)

Two-tier device settings with vendor-agnostic abstractions and vendor-specific overrides. All fields are optional — omitted fields inherit from the parent configuration layer (Global defaults → Platform → Account → Device).

This schema evolves as new hardware capabilities are supported. The vendor_overrides field provides an escape hatch for vendor-specific parameters not yet covered by abstractions.

ipei
string

DECT handset IPEI

display_name
string
Deprecated

Deprecated alias of name for DECT handset updates. Send name instead. If both are present, name wins.

location_id
string or null

Physical E911 location (deskphone or DECT base only). Tri-state: omit for no change, send a loc_… ID to set, or send explicit JSON null to clear the device's dispatch location.

base_id
string or null

Paired DECT base (DECT handset only). Tri-state: omit for no change, send a dectb_… ID to re-pair to a different base on the same account, or send explicit JSON null to unpair the handset (it remains in inventory and can be paired later).

Responses

Response Schema: application/json
id
required
string

Unique identifier

type
required
string
Enum: "deskphone" "dect_base" "dect_handset"

The kind of device

mac_address
required
string

Hardware MAC address

vendor
required
string

Device vendor (auto-detected from MAC address)

model
string or null

Device model

name
string or null

Human-friendly label for the device. Set by admins on deskphones, DECT bases, and DECT handsets; null when unassigned. Handset responses also expose this value as display_name for backwards compatibility with older clients.

location_id
string or null

Physical E911 location for this device. Set on deskphones and DECT bases; null when unassigned. DECT handsets have no location_id of their own — they inherit from the paired base and the handset response carries null here. See the E911 guide for the dispatch resolution rules.

status
required
string
Enum: "pending-sync" "provisioned"

Current provisioning status

object or null

Device-specific settings overrides

current_ip_address
string or null

Last known IP address of the device

last_provisioned_at
string or null <date-time>

When the device last fetched its configuration

created_at
required
string <date-time> (CreatedAt)

Timestamp when it was created

updated_at
required
string <date-time> (UpdatedAt)

Timestamp when it was last updated

primary_line_id
string or null

Primary SIP line (deskphone only)

Array of objects (DeviceLine)

SIP line assignments (deskphone only)

multicell_role
string or null
Enum: "single" "data_master" "secondary" null

Role in a multicell deployment (DECT base only)

max_handsets
integer or null

Maximum number of handsets supported (DECT base only)

firmware_version
string or null

Current firmware version (DECT bases and handsets)

Array of objects (DECTHandset)

Paired handsets (DECT base only)

base_id
string or null

Parent DECT base station (DECT handset only)

ipei
string or null

DECT handset IPEI (DECT handset only)

display_name
string or null

Optional display name (DECT handset only)

slot_number
integer or null

Slot number on the base station (DECT handset only)

registered_at
string or null <date-time>

When the handset registered with the base (DECT handset only)

Array of objects (HandsetLine)

SIP line assignments on this handset (DECT handset only)

Array of objects (DeviceUserAssignment)

User assignments. Only included when expand[]=users is requested.

Request samples

Content type
application/json
{
  • "model": "string",
  • "name": "string",
  • "status": "pending-sync",
  • "overrides": {
    },
  • "ipei": "string",
  • "display_name": "string",
  • "location_id": "string",
  • "base_id": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "deskphone",
  • "mac_address": "00:04:13:aa:bb:cc",
  • "vendor": "snom",
  • "model": "D785",
  • "name": "string",
  • "location_id": "string",
  • "status": "pending-sync",
  • "overrides": {
    },
  • "current_ip_address": "192.168.1.100",
  • "last_provisioned_at": "2019-08-24T14:15:22Z",
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z",
  • "primary_line_id": "string",
  • "lines": [
    ],
  • "multicell_role": "single",
  • "max_handsets": 30,
  • "firmware_version": "string",
  • "handsets": [
    ],
  • "base_id": "string",
  • "ipei": "string",
  • "display_name": "string",
  • "slot_number": 0,
  • "registered_at": "2019-08-24T14:15:22Z",
  • "extensions": [
    ],
  • "assignments": [
    ]
}

Delete a device

Recommended way to delete any device. Prefer this endpoint over DELETE /v1/deskphones/{id}, DELETE /v1/dect-bases/{id}, and DELETE /v1/dect-bases/{id}/handsets/{handset_id}.

Delete any device by its ID. Works for deskphones, DECT base stations, and DECT handsets.

Deleting a deskphone removes all associated user assignments. Deleting a DECT base removes all its handsets and their user assignments.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string

Device identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Request samples 

curl -X DELETE \
  https://api.dialstack.ai/v1/devices/%7Bid%7D \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "error": "Invalid request body",
  • "code": "validation_error",
  • "details": { }
}

Trigger device configuration reload

Tells the device to fetch and apply its latest configuration. Works for deskphones, DECT bases, and DECT handsets — on a DECT system, one request reloads configuration on every handset paired with the base.

With the default reboot: false, the device applies configuration in place. Active calls continue and the device stays registered. With reboot: true, the device reboots immediately — any active call is dropped, and the device is offline for about 30–90 seconds.

Trigger check-sync when you actually change configuration, not on every admin-UI interaction. See the Device provisioning guide for the full list of side effects.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string

Device identifier (deskphone, DECT base, or DECT handset)

Request Body schema: application/json
optional
reboot
boolean
Default: false

If true, the device reboots immediately after applying config, interrupting any active call. Default false performs a non-disruptive config reload.

Responses

Response Schema: application/json
success
required
boolean
lines_notified
required
integer

Number of lines that accepted the request.

required
Array of objects

Per-line outcome. line_number is a 1-indexed identifier; for deskphones it matches the physical line, for DECT it is a stable sequence within the response.

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "success": true,
  • "lines_notified": 1,
  • "lines": [
    ]
}

Assign a user to a device

Assigns a user to a device. SIP credentials and line configuration are created automatically.

Supported device types:

  • Deskphones — assigns the user to the next available line key (max 24)
  • DECT handsets — assigns the user to the handset (max 24)
  • DECT bases — not supported (returns 400); assign to individual handsets instead
Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string

Device identifier (deskphone, DECT handset, or DECT base)

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
user_id
required
string

The user to assign to the deskphone

Responses

Response Schema: application/json
user_id
required
string

Unique identifier

device_id
required
string

Unique identifier

line_number
integer [ 1 .. 24 ]

Physical line key number assigned to this user

created_at
required
string <date-time> (CreatedAt)

Timestamp when it was created

Request samples

Content type
application/json
{
  • "user_id": "user_01h2xcejqtf2nbrexx3vqjhp42"
}

Response samples

Content type
application/json
{
  • "user_id": "01h2xcejqtf2nbrexx3vqjhp42",
  • "device_id": "01h2xcejqtf2nbrexx3vqjhp50",
  • "line_number": 1,
  • "created_at": "2025-10-17T14:30:00Z"
}

List users assigned to a device

Returns all users currently assigned to the device. Devices support at most 24 users, so no pagination is needed.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string

Device identifier (deskphone, DECT handset, or DECT base)

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
object
required
string
Value: "list"
url
required
string
next_page_url
string or null
previous_page_url
string or null
required
Array of objects (DeviceUserAssignment)

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/devices/%7Bid%7D/users \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "object": "list",
  • "url": "string",
  • "next_page_url": "string",
  • "previous_page_url": "string",
  • "data": [
    ]
}

Remove a user from a device

Removes the user's assignment from the device. The associated SIP credentials and line configuration are cleaned up automatically.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string

Device identifier (deskphone, DECT handset, or DECT base)

user_id
required
string
Example: user_01h2xcejqtf2nbrexx3vqjhp42

User identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Request samples 

curl -X DELETE \
  https://api.dialstack.ai/v1/devices/%7Bid%7D/users/user_01h2xcejqtf2nbrexx3vqjhp42 \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "error": "Invalid request body",
  • "code": "validation_error",
  • "details": { }
}

Deskphones

Deskphone-specific operations retained for the cases /v1/devices does not cover yet (updates and provisioning events). For create, list, get, and delete, use the unified Devices API — it is the recommended approach for all new integrations.

Requires account context via DialStack-Account header or session token.

Create a deskphone Deprecated

Deprecated: Use POST /v1/devices with type: deskphone instead.

Provision a new deskphone. The vendor is auto-detected from the MAC address.

Authorizations:
BearerAuthSessionAuth
header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
mac_address
required
string

Hardware MAC address (vendor is auto-detected)

model
string

Device model (optional)

object or null (DeviceSettings)

Two-tier device settings with vendor-agnostic abstractions and vendor-specific overrides. All fields are optional — omitted fields inherit from the parent configuration layer (Global defaults → Platform → Account → Device).

This schema evolves as new hardware capabilities are supported. The vendor_overrides field provides an escape hatch for vendor-specific parameters not yet covered by abstractions.

Responses

Response Schema: application/json
id
required
string

Unique identifier

mac_address
required
string

Hardware MAC address

vendor
required
string

Device vendor (auto-detected from MAC address)

model
string or null

Device model

name
string or null

Human-friendly label for the device. null when unassigned.

location_id
string or null

Physical E911 location for this deskphone. null when unassigned. See the E911 guide for the dispatch resolution rules.

status
required
string
Enum: "pending-sync" "provisioned"

Current provisioning status

object or null

Device-specific settings overrides

current_ip_address
string or null

Last known IP address of the device

last_provisioned_at
string or null <date-time>

When the device last fetched its configuration

created_at
required
string <date-time> (CreatedAt)

Timestamp when it was created

updated_at
required
string <date-time> (UpdatedAt)

Timestamp when it was last updated

primary_line_id
string or null

Primary SIP line

Array of objects (DeviceLine)

SIP line assignments

Request samples

Content type
application/json
{
  • "mac_address": "00:04:13:aa:bb:cc",
  • "model": "D785"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "mac_address": "00:04:13:aa:bb:cc",
  • "vendor": "snom",
  • "model": "D785",
  • "name": "string",
  • "location_id": "string",
  • "status": "pending-sync",
  • "overrides": {
    },
  • "current_ip_address": "192.168.1.100",
  • "last_provisioned_at": "2019-08-24T14:15:22Z",
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z",
  • "primary_line_id": "string",
  • "lines": [
    ]
}

List deskphones Deprecated

Deprecated: Use GET /v1/devices?type=deskphone instead.

List all deskphones for the account. Results are returned in reverse chronological order (newest first).

Authorizations:
BearerAuthSessionAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

Number of objects to return. Defaults to 10. Maximum is 100.

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
object
required
string (ListObject)
Value: "list"

String representing the object's type. Always "list" for list responses.

url
required
string (ListUrl)

The URL for accessing this list.

next_page_url
required
string or null (NextPageUrl)

URL to fetch the next page of results. If null, there are no more pages. The URL includes all necessary parameters including the pagination cursor.

previous_page_url
required
string or null (PreviousPageUrl)

URL to fetch the previous page of results. If null, this is the first page. The URL includes all necessary parameters including the pagination cursor.

required
Array of objects (ProvisionedDevice)

Request samples 

curl -X GET \
  'https://api.dialstack.ai/v1/deskphones?limit=10' \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "object": "list",
  • "url": "/v1/accounts",
  • "next_page_url": "/v1/accounts?page=eyJzdGFydGluZ19hZnRlciI6ImFjY3RfMDFoMnhjZWpxdGYybmJyZXh4M3ZxamhwNDEiLCJsaW1pdCI6MTB9",
  • "previous_page_url": "/v1/accounts?page=eyJlbmRpbmdfYmVmb3JlIjoiYWNjdF8wMWgyeGNlanF0ZjJuYnJleHgzdnFqaHA0MSIsImxpbWl0IjoxMH0",
  • "data": [
    ]
}

Get a deskphone Deprecated

Deprecated: Use GET /v1/devices/{id} instead.

Retrieve a deskphone by its ID.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string

Deskphone identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
id
required
string

Unique identifier

mac_address
required
string

Hardware MAC address

vendor
required
string

Device vendor (auto-detected from MAC address)

model
string or null

Device model

name
string or null

Human-friendly label for the device. null when unassigned.

location_id
string or null

Physical E911 location for this deskphone. null when unassigned. See the E911 guide for the dispatch resolution rules.

status
required
string
Enum: "pending-sync" "provisioned"

Current provisioning status

object or null

Device-specific settings overrides

current_ip_address
string or null

Last known IP address of the device

last_provisioned_at
string or null <date-time>

When the device last fetched its configuration

created_at
required
string <date-time> (CreatedAt)

Timestamp when it was created

updated_at
required
string <date-time> (UpdatedAt)

Timestamp when it was last updated

primary_line_id
string or null

Primary SIP line

Array of objects (DeviceLine)

SIP line assignments

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/deskphones/%7Bid%7D \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "id": "string",
  • "mac_address": "00:04:13:aa:bb:cc",
  • "vendor": "snom",
  • "model": "D785",
  • "name": "string",
  • "location_id": "string",
  • "status": "pending-sync",
  • "overrides": {
    },
  • "current_ip_address": "192.168.1.100",
  • "last_provisioned_at": "2019-08-24T14:15:22Z",
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z",
  • "primary_line_id": "string",
  • "lines": [
    ]
}

Update a deskphone

Update a deskphone's properties. Only provided fields are changed.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string

Deskphone identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
model
string

Device model

status
string
Enum: "pending-sync" "provisioned"

Device status

object or null (DeviceSettings)

Two-tier device settings with vendor-agnostic abstractions and vendor-specific overrides. All fields are optional — omitted fields inherit from the parent configuration layer (Global defaults → Platform → Account → Device).

This schema evolves as new hardware capabilities are supported. The vendor_overrides field provides an escape hatch for vendor-specific parameters not yet covered by abstractions.

Responses

Response Schema: application/json
id
required
string

Unique identifier

mac_address
required
string

Hardware MAC address

vendor
required
string

Device vendor (auto-detected from MAC address)

model
string or null

Device model

name
string or null

Human-friendly label for the device. null when unassigned.

location_id
string or null

Physical E911 location for this deskphone. null when unassigned. See the E911 guide for the dispatch resolution rules.

status
required
string
Enum: "pending-sync" "provisioned"

Current provisioning status

object or null

Device-specific settings overrides

current_ip_address
string or null

Last known IP address of the device

last_provisioned_at
string or null <date-time>

When the device last fetched its configuration

created_at
required
string <date-time> (CreatedAt)

Timestamp when it was created

updated_at
required
string <date-time> (UpdatedAt)

Timestamp when it was last updated

primary_line_id
string or null

Primary SIP line

Array of objects (DeviceLine)

SIP line assignments

Request samples

Content type
application/json
{
  • "model": "string",
  • "status": "pending-sync",
  • "overrides": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "mac_address": "00:04:13:aa:bb:cc",
  • "vendor": "snom",
  • "model": "D785",
  • "name": "string",
  • "location_id": "string",
  • "status": "pending-sync",
  • "overrides": {
    },
  • "current_ip_address": "192.168.1.100",
  • "last_provisioned_at": "2019-08-24T14:15:22Z",
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z",
  • "primary_line_id": "string",
  • "lines": [
    ]
}

Delete a deskphone Deprecated

Deprecated: Use DELETE /v1/devices/{id} instead.

Delete a deskphone and all its associated lines.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string

Deskphone identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Request samples 

curl -X DELETE \
  https://api.dialstack.ai/v1/deskphones/%7Bid%7D \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "error": "Invalid request body",
  • "code": "validation_error",
  • "details": { }
}

List provisioning events

List provisioning events for a deskphone. Returns a log of configuration fetches by the device.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string

Deskphone identifier

query Parameters
limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

Number of objects to return. Defaults to 10. Maximum is 100.

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
object
required
string (ListObject)
Value: "list"

String representing the object's type. Always "list" for list responses.

url
required
string (ListUrl)

The URL for accessing this list.

next_page_url
required
string or null (NextPageUrl)

URL to fetch the next page of results. If null, there are no more pages. The URL includes all necessary parameters including the pagination cursor.

previous_page_url
required
string or null (PreviousPageUrl)

URL to fetch the previous page of results. If null, this is the first page. The URL includes all necessary parameters including the pagination cursor.

required
Array of objects (ProvisioningEvent)

Request samples 

curl -X GET \
  'https://api.dialstack.ai/v1/deskphones/%7Bid%7D/provisioning-events?limit=10' \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "object": "list",
  • "url": "/v1/accounts",
  • "next_page_url": "/v1/accounts?page=eyJzdGFydGluZ19hZnRlciI6ImFjY3RfMDFoMnhjZWpxdGYybmJyZXh4M3ZxamhwNDEiLCJsaW1pdCI6MTB9",
  • "previous_page_url": "/v1/accounts?page=eyJlbmRpbmdfYmVmb3JlIjoiYWNjdF8wMWgyeGNlanF0ZjJuYnJleHgzdnFqaHA0MSIsImxpbWl0IjoxMH0",
  • "data": [
    ]
}

Create a deskphone line Deprecated

Deprecated: Use POST /v1/devices/{id}/users instead.

Assigns a SIP endpoint to the next available line key on the deskphone. The line number is automatically assigned as the lowest unused number (1-24). A deskphone supports a maximum of 24 lines. Each endpoint can only be assigned once per device.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string

Deskphone identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
endpoint_id
required
string

ID of the SIP endpoint to assign to this line

Responses

Response Schema: application/json
id
required
string

Unique identifier

device_id
required
string

Unique identifier

endpoint_id
required
string

Unique identifier

line_number
required
integer [ 1 .. 24 ]

Physical line key number on the device

created_at
required
string <date-time> (CreatedAt)

Timestamp when it was created

updated_at
required
string <date-time> (UpdatedAt)

Timestamp when it was last updated

Request samples

Content type
application/json
{
  • "endpoint_id": "ep_01h2xcejqtf2nbrexx3vqjhp43"
}

Response samples

Content type
application/json
{
  • "id": "dln_01h2xcejqtf2nbrexx3vqjhp55",
  • "device_id": "dev_01h2xcejqtf2nbrexx3vqjhp50",
  • "endpoint_id": "ep_01h2xcejqtf2nbrexx3vqjhp43",
  • "line_number": 1,
  • "created_at": "2025-10-18T10:00:00Z",
  • "updated_at": "2025-10-18T10:00:00Z"
}

List deskphone lines Deprecated

Deprecated: Use GET /v1/devices/{id}/users instead.

List all SIP line assignments for a deskphone. Returns lines ordered by line number.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string

Deskphone identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
required
Array of objects (DeviceLine)
Array
id
required
string

Unique identifier

device_id
required
string

Unique identifier

endpoint_id
required
string

Unique identifier

line_number
required
integer [ 1 .. 24 ]

Physical line key number on the device

created_at
required
string <date-time> (CreatedAt)

Timestamp when it was created

updated_at
required
string <date-time> (UpdatedAt)

Timestamp when it was last updated

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/deskphones/%7Bid%7D/lines \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Update a deskphone line Deprecated

Deprecated: Use DELETE /v1/devices/{id}/users/{user_id} and POST /v1/devices/{id}/users instead.

Reassigns a deskphone line to a different SIP endpoint. The line number remains unchanged; only the endpoint is updated.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string

Deskphone identifier

line_id
required
string
Example: dln_01h2xcejqtf2nbrexx3vqjhp55

Device line identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
endpoint_id
required
string

ID of the new SIP endpoint to assign to this line

Responses

Response Schema: application/json
id
required
string

Unique identifier

device_id
required
string

Unique identifier

endpoint_id
required
string

Unique identifier

line_number
required
integer [ 1 .. 24 ]

Physical line key number on the device

created_at
required
string <date-time> (CreatedAt)

Timestamp when it was created

updated_at
required
string <date-time> (UpdatedAt)

Timestamp when it was last updated

Request samples

Content type
application/json
{
  • "endpoint_id": "ep_01h2xcejqtf2nbrexx3vqjhp44"
}

Response samples

Content type
application/json
{
  • "id": "dln_01h2xcejqtf2nbrexx3vqjhp55",
  • "device_id": "dev_01h2xcejqtf2nbrexx3vqjhp50",
  • "endpoint_id": "ep_01h2xcejqtf2nbrexx3vqjhp43",
  • "line_number": 1,
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

Delete a deskphone line Deprecated

Deprecated: Use DELETE /v1/devices/{id}/users/{user_id} instead.

Removes a SIP line assignment from the deskphone.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string

Deskphone identifier

line_id
required
string
Example: dln_01h2xcejqtf2nbrexx3vqjhp55

Device line identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Request samples 

curl -X DELETE \
  https://api.dialstack.ai/v1/deskphones/%7Bid%7D/lines/dln_01h2xcejqtf2nbrexx3vqjhp55 \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "error": "Invalid request body",
  • "code": "validation_error",
  • "details": { }
}

DECT Bases

DECT-specific operations retained for the cases /v1/devices does not cover yet (updates and listing handsets under a specific base). For create, list, get, and delete of bases and handsets, use the unified Devices API — it is the recommended approach for all new integrations.

Requires account context via DialStack-Account header or session token.

Create a DECT base station Deprecated

Deprecated: Use POST /v1/devices with type: dect_base instead.

Register a new DECT base station for provisioning. The vendor is automatically detected from the MAC address.

Authorizations:
BearerAuthSessionAuth
header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
mac_address
required
string

Hardware MAC address (vendor is auto-detected)

model
string

Base station model (optional, can be auto-detected)

multicell_role
string
Enum: "single" "data_master" "secondary"

Role in multicell deployment (defaults to single)

object or null (DeviceSettings)

Two-tier device settings with vendor-agnostic abstractions and vendor-specific overrides. All fields are optional — omitted fields inherit from the parent configuration layer (Global defaults → Platform → Account → Device).

This schema evolves as new hardware capabilities are supported. The vendor_overrides field provides an escape hatch for vendor-specific parameters not yet covered by abstractions.

Responses

Response Schema: application/json
id
required
string

Unique identifier

mac_address
required
string

Hardware MAC address

vendor
required
string

Device vendor (auto-detected from MAC address)

model
string or null

Base station model

name
string or null

Human-friendly label for the base. null when unassigned.

status
required
string
Enum: "pending-sync" "provisioned"

Current provisioning status

multicell_role
required
string
Enum: "single" "data_master" "secondary"

Role in a multicell deployment:

  • single — standalone base station (default)
  • data_master — primary base that distributes configuration
  • secondary — subordinate base that receives configuration from the data master
max_handsets
required
integer

Maximum number of handsets this base supports

firmware_version
string or null

Current firmware version

object or null

Device-specific settings overrides

current_ip_address
string or null

Last known IP address of the base station

last_provisioned_at
string or null <date-time>

When the base last fetched its configuration

location_id
string or null

Physical location used as the emergency-services dispatch address when any handset on this base places a call. All handsets paired with this base share the same location.

Array of objects (DECTHandset)

Paired wireless handsets

created_at
required
string <date-time> (CreatedAt)

Timestamp when it was created

updated_at
required
string <date-time> (UpdatedAt)

Timestamp when it was last updated

Request samples

Content type
application/json
Example
{
  • "mac_address": "00:04:13:bb:cc:dd"
}

Response samples

Content type
application/json
{
  • "id": "dectb_01h2xcejqtf2nbrexx3vqjhp60",
  • "mac_address": "00:04:13:bb:cc:dd",
  • "vendor": "snom",
  • "model": null,
  • "status": "pending-sync",
  • "multicell_role": "single",
  • "max_handsets": 30,
  • "created_at": "2025-10-18T10:00:00Z",
  • "updated_at": "2025-10-18T10:00:00Z"
}

List DECT base stations Deprecated

Deprecated: Use GET /v1/devices?type=dect_base instead.

List all DECT base stations in the account.

Authorizations:
BearerAuthSessionAuth
header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
object
required
string (ListObject)
Value: "list"

String representing the object's type. Always "list" for list responses.

url
required
string (ListUrl)

The URL for accessing this list.

next_page_url
required
string or null (NextPageUrl)

URL to fetch the next page of results. If null, there are no more pages. The URL includes all necessary parameters including the pagination cursor.

previous_page_url
required
string or null (PreviousPageUrl)

URL to fetch the previous page of results. If null, this is the first page. The URL includes all necessary parameters including the pagination cursor.

required
Array of objects (DECTBase)

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/dect-bases \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "object": "list",
  • "url": "/v1/accounts",
  • "next_page_url": "/v1/accounts?page=eyJzdGFydGluZ19hZnRlciI6ImFjY3RfMDFoMnhjZWpxdGYybmJyZXh4M3ZxamhwNDEiLCJsaW1pdCI6MTB9",
  • "previous_page_url": "/v1/accounts?page=eyJlbmRpbmdfYmVmb3JlIjoiYWNjdF8wMWgyeGNlanF0ZjJuYnJleHgzdnFqaHA0MSIsImxpbWl0IjoxMH0",
  • "data": [
    ]
}

Get a DECT base station Deprecated

Deprecated: Use GET /v1/devices/{id} instead.

Retrieve a DECT base station by ID.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string

DECT base station identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
id
required
string

Unique identifier

mac_address
required
string

Hardware MAC address

vendor
required
string

Device vendor (auto-detected from MAC address)

model
string or null

Base station model

name
string or null

Human-friendly label for the base. null when unassigned.

status
required
string
Enum: "pending-sync" "provisioned"

Current provisioning status

multicell_role
required
string
Enum: "single" "data_master" "secondary"

Role in a multicell deployment:

  • single — standalone base station (default)
  • data_master — primary base that distributes configuration
  • secondary — subordinate base that receives configuration from the data master
max_handsets
required
integer

Maximum number of handsets this base supports

firmware_version
string or null

Current firmware version

object or null

Device-specific settings overrides

current_ip_address
string or null

Last known IP address of the base station

last_provisioned_at
string or null <date-time>

When the base last fetched its configuration

location_id
string or null

Physical location used as the emergency-services dispatch address when any handset on this base places a call. All handsets paired with this base share the same location.

Array of objects (DECTHandset)

Paired wireless handsets

created_at
required
string <date-time> (CreatedAt)

Timestamp when it was created

updated_at
required
string <date-time> (UpdatedAt)

Timestamp when it was last updated

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/dect-bases/%7Bid%7D \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "id": "string",
  • "mac_address": "00:04:13:bb:cc:dd",
  • "vendor": "snom",
  • "model": "M500",
  • "name": "string",
  • "status": "pending-sync",
  • "multicell_role": "single",
  • "max_handsets": 30,
  • "firmware_version": "string",
  • "overrides": {
    },
  • "current_ip_address": "192.168.1.101",
  • "last_provisioned_at": "2019-08-24T14:15:22Z",
  • "location_id": "string",
  • "handsets": [
    ],
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

Update a DECT base station

Update properties of a DECT base station.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string

DECT base station identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
model
string

Base station model

status
string
Enum: "pending-sync" "provisioned"

Device status

multicell_role
string
Enum: "single" "data_master" "secondary"

Role in multicell deployment

object or null (DeviceSettings)

Two-tier device settings with vendor-agnostic abstractions and vendor-specific overrides. All fields are optional — omitted fields inherit from the parent configuration layer (Global defaults → Platform → Account → Device).

This schema evolves as new hardware capabilities are supported. The vendor_overrides field provides an escape hatch for vendor-specific parameters not yet covered by abstractions.

Responses

Response Schema: application/json
id
required
string

Unique identifier

mac_address
required
string

Hardware MAC address

vendor
required
string

Device vendor (auto-detected from MAC address)

model
string or null

Base station model

name
string or null

Human-friendly label for the base. null when unassigned.

status
required
string
Enum: "pending-sync" "provisioned"

Current provisioning status

multicell_role
required
string
Enum: "single" "data_master" "secondary"

Role in a multicell deployment:

  • single — standalone base station (default)
  • data_master — primary base that distributes configuration
  • secondary — subordinate base that receives configuration from the data master
max_handsets
required
integer

Maximum number of handsets this base supports

firmware_version
string or null

Current firmware version

object or null

Device-specific settings overrides

current_ip_address
string or null

Last known IP address of the base station

last_provisioned_at
string or null <date-time>

When the base last fetched its configuration

location_id
string or null

Physical location used as the emergency-services dispatch address when any handset on this base places a call. All handsets paired with this base share the same location.

Array of objects (DECTHandset)

Paired wireless handsets

created_at
required
string <date-time> (CreatedAt)

Timestamp when it was created

updated_at
required
string <date-time> (UpdatedAt)

Timestamp when it was last updated

Request samples

Content type
application/json
Example
{
  • "multicell_role": "data_master"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "mac_address": "00:04:13:bb:cc:dd",
  • "vendor": "snom",
  • "model": "M500",
  • "name": "string",
  • "status": "pending-sync",
  • "multicell_role": "single",
  • "max_handsets": 30,
  • "firmware_version": "string",
  • "overrides": {
    },
  • "current_ip_address": "192.168.1.101",
  • "last_provisioned_at": "2019-08-24T14:15:22Z",
  • "location_id": "string",
  • "handsets": [
    ],
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

Delete a DECT base station Deprecated

Deprecated: Use DELETE /v1/devices/{id} instead.

Delete a DECT base station and all associated handsets and extensions.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string

DECT base station identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Request samples 

curl -X DELETE \
  https://api.dialstack.ai/v1/dect-bases/%7Bid%7D \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "error": "Invalid request body",
  • "code": "validation_error",
  • "details": { }
}

Add a handset to a DECT base Deprecated

Deprecated: Use POST /v1/devices with type: dect_handset and base_id set to the DECT base identifier instead.

Pair a new wireless handset with a DECT base station. The slot number is automatically assigned as the lowest available slot. IPEI (International Portable Equipment Identity) is a unique hardware identifier for wireless handsets, formatted as a hexadecimal string up to 20 characters.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string

DECT base station identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
ipei
required
string

International Portable Equipment Identity

display_name
string

Optional display name

model
string

Handset model

Responses

Response Schema: application/json
id
required
string

Unique identifier

base_id
string or null

Parent DECT base station. null when the handset is stocked but not yet paired with a base — pair later by updating this field with a base ID.

ipei
required
string

International Portable Equipment Identity

status
required
string
Enum: "unpaired" "pending-sync" "registered" "provisioned"

Current handset status

display_name
string or null

Optional display name

slot_number
required
integer

Slot number on the base station

model
string or null

Handset model

firmware_version
string or null

Current firmware version

registered_at
string or null <date-time>

When the handset was registered with the base

Array of objects (HandsetLine)

SIP line assignments on this handset

created_at
required
string <date-time> (CreatedAt)

Timestamp when it was created

updated_at
required
string <date-time> (UpdatedAt)

Timestamp when it was last updated

Request samples

Content type
application/json
{
  • "ipei": "0328A0000F",
  • "display_name": "Front Desk"
}

Response samples

Content type
application/json
{
  • "id": "decth_01h2xcejqtf2nbrexx3vqjhp70",
  • "base_id": "dectb_01h2xcejqtf2nbrexx3vqjhp60",
  • "ipei": "0328A0000F",
  • "status": "pending-sync",
  • "display_name": "Front Desk",
  • "slot_number": 1,
  • "created_at": "2025-10-18T10:00:00Z",
  • "updated_at": "2025-10-18T10:00:00Z"
}

List handsets on a DECT base

List all wireless handsets paired with a DECT base station.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string

DECT base station identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
object
required
string (ListObject)
Value: "list"

String representing the object's type. Always "list" for list responses.

url
required
string (ListUrl)

The URL for accessing this list.

next_page_url
required
string or null (NextPageUrl)

URL to fetch the next page of results. If null, there are no more pages. The URL includes all necessary parameters including the pagination cursor.

previous_page_url
required
string or null (PreviousPageUrl)

URL to fetch the previous page of results. If null, this is the first page. The URL includes all necessary parameters including the pagination cursor.

required
Array of objects (DECTHandset)

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/dect-bases/%7Bid%7D/handsets \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "object": "list",
  • "url": "/v1/accounts",
  • "next_page_url": "/v1/accounts?page=eyJzdGFydGluZ19hZnRlciI6ImFjY3RfMDFoMnhjZWpxdGYybmJyZXh4M3ZxamhwNDEiLCJsaW1pdCI6MTB9",
  • "previous_page_url": "/v1/accounts?page=eyJlbmRpbmdfYmVmb3JlIjoiYWNjdF8wMWgyeGNlanF0ZjJuYnJleHgzdnFqaHA0MSIsImxpbWl0IjoxMH0",
  • "data": [
    ]
}

Get a handset Deprecated

Deprecated: Use GET /v1/devices/{id} with the handset ID instead.

Retrieve a specific handset.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string

DECT base station identifier

handset_id
required
string

Handset identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
id
required
string

Unique identifier

base_id
string or null

Parent DECT base station. null when the handset is stocked but not yet paired with a base — pair later by updating this field with a base ID.

ipei
required
string

International Portable Equipment Identity

status
required
string
Enum: "unpaired" "pending-sync" "registered" "provisioned"

Current handset status

display_name
string or null

Optional display name

slot_number
required
integer

Slot number on the base station

model
string or null

Handset model

firmware_version
string or null

Current firmware version

registered_at
string or null <date-time>

When the handset was registered with the base

Array of objects (HandsetLine)

SIP line assignments on this handset

created_at
required
string <date-time> (CreatedAt)

Timestamp when it was created

updated_at
required
string <date-time> (UpdatedAt)

Timestamp when it was last updated

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/dect-bases/%7Bid%7D/handsets/%7Bhandset_id%7D \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "id": "string",
  • "base_id": "string",
  • "ipei": "0328A0000F",
  • "status": "unpaired",
  • "display_name": "string",
  • "slot_number": 1,
  • "model": "string",
  • "firmware_version": "string",
  • "registered_at": "2019-08-24T14:15:22Z",
  • "extensions": [
    ],
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

Update a handset

Update handset properties such as IPEI or display name.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string

DECT base station identifier

handset_id
required
string

Handset identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
ipei
string

International Portable Equipment Identity

display_name
string

Display name

Responses

Response Schema: application/json
id
required
string

Unique identifier

base_id
string or null

Parent DECT base station. null when the handset is stocked but not yet paired with a base — pair later by updating this field with a base ID.

ipei
required
string

International Portable Equipment Identity

status
required
string
Enum: "unpaired" "pending-sync" "registered" "provisioned"

Current handset status

display_name
string or null

Optional display name

slot_number
required
integer

Slot number on the base station

model
string or null

Handset model

firmware_version
string or null

Current firmware version

registered_at
string or null <date-time>

When the handset was registered with the base

Array of objects (HandsetLine)

SIP line assignments on this handset

created_at
required
string <date-time> (CreatedAt)

Timestamp when it was created

updated_at
required
string <date-time> (UpdatedAt)

Timestamp when it was last updated

Request samples

Content type
application/json
{
  • "display_name": "Warehouse"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "base_id": "string",
  • "ipei": "0328A0000F",
  • "status": "unpaired",
  • "display_name": "string",
  • "slot_number": 1,
  • "model": "string",
  • "firmware_version": "string",
  • "registered_at": "2019-08-24T14:15:22Z",
  • "extensions": [
    ],
  • "created_at": "2025-10-17T14:30:00Z",
  • "updated_at": "2025-10-17T14:30:00Z"
}

Delete a handset Deprecated

Deprecated: Use DELETE /v1/devices/{id} with the handset ID instead.

Remove a handset from a DECT base station. All extensions on the handset are also removed.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string

DECT base station identifier

handset_id
required
string

Handset identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Request samples 

curl -X DELETE \
  https://api.dialstack.ai/v1/dect-bases/%7Bid%7D/handsets/%7Bhandset_id%7D \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "error": "Invalid request body",
  • "code": "validation_error",
  • "details": { }
}

Assign an extension to a handset Deprecated

Deprecated: Use POST /v1/devices/{id}/users with the handset ID instead.

Assign a SIP endpoint to a DECT handset as an extension (SIP line).

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string

DECT base station identifier

handset_id
required
string

Handset identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Request Body schema: application/json
required
endpoint_id
required
string

ID of the SIP endpoint to assign

display_name
string

Optional display name override

Responses

Response Schema: application/json
id
required
string

Unique identifier

handset_id
required
string

Unique identifier

endpoint_id
required
string

Unique identifier

display_name
string or null

Optional display name override

object or null

The associated SIP endpoint (included on list responses)

created_at
required
string <date-time> (CreatedAt)

Timestamp when it was created

updated_at
required
string <date-time> (UpdatedAt)

Timestamp when it was last updated

Request samples

Content type
application/json
{
  • "endpoint_id": "ep_01h2xcejqtf2nbrexx3vqjhp43"
}

Response samples

Content type
application/json
{
  • "id": "decte_01h2xcejqtf2nbrexx3vqjhp80",
  • "handset_id": "decth_01h2xcejqtf2nbrexx3vqjhp70",
  • "endpoint_id": "ep_01h2xcejqtf2nbrexx3vqjhp43",
  • "display_name": null,
  • "created_at": "2025-10-18T10:00:00Z",
  • "updated_at": "2025-10-18T10:00:00Z"
}

List extensions on a handset Deprecated

Deprecated: Use GET /v1/devices/{id}/users with the handset ID instead.

List all SIP line assignments on a DECT handset.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string

DECT base station identifier

handset_id
required
string

Handset identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
object
required
string (ListObject)
Value: "list"

String representing the object's type. Always "list" for list responses.

url
required
string (ListUrl)

The URL for accessing this list.

next_page_url
required
string or null (NextPageUrl)

URL to fetch the next page of results. If null, there are no more pages. The URL includes all necessary parameters including the pagination cursor.

previous_page_url
required
string or null (PreviousPageUrl)

URL to fetch the previous page of results. If null, this is the first page. The URL includes all necessary parameters including the pagination cursor.

required
Array of objects (HandsetLine)

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/dect-bases/%7Bid%7D/handsets/%7Bhandset_id%7D/extensions \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "object": "list",
  • "url": "/v1/accounts",
  • "next_page_url": "/v1/accounts?page=eyJzdGFydGluZ19hZnRlciI6ImFjY3RfMDFoMnhjZWpxdGYybmJyZXh4M3ZxamhwNDEiLCJsaW1pdCI6MTB9",
  • "previous_page_url": "/v1/accounts?page=eyJlbmRpbmdfYmVmb3JlIjoiYWNjdF8wMWgyeGNlanF0ZjJuYnJleHgzdnFqaHA0MSIsImxpbWl0IjoxMH0",
  • "data": [
    ]
}

Remove an extension from a handset Deprecated

Deprecated: Use DELETE /v1/devices/{id}/users/{user_id} with the handset ID instead.

Remove a SIP line assignment from a DECT handset.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string

DECT base station identifier

handset_id
required
string

Handset identifier

extension_id
required
string

Extension identifier

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Request samples 

curl -X DELETE \
  https://api.dialstack.ai/v1/dect-bases/%7Bid%7D/handsets/%7Bhandset_id%7D/extensions/%7Bextension_id%7D \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "error": "Invalid request body",
  • "code": "validation_error",
  • "details": { }
}

Hardware Orders

Hardware order management. Orders contain line items representing hardware selections (model + quantity). Requires account context via DialStack-Account header or session token.

Create hardware order

Creates a new hardware order in draft status with the given items. Each item references a hardware catalog entry with a quantity.

Authorizations:
BearerAuthSessionAuth
Request Body schema: application/json
required
required
Array of objects non-empty
Array (non-empty)
hardware_catalog_id
required
string

ID of the hardware catalog item

quantity
required
integer [ 1 .. 100 ]

Responses

Response Schema: application/json
id
string

Hardware order ID

status
string
Enum: "draft" "submitted" "fulfilled" "cancelled"

Order lifecycle status

Array of objects (HardwareOrderItem)

Line items in the order

created_at
string <date-time>
updated_at
string <date-time>

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "draft",
  • "items": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List hardware orders

Returns all hardware orders for the account, including embedded items.

Authorizations:
BearerAuthSessionAuth

Responses

Response Schema: application/json
object
string
url
string
Array of objects (HardwareOrder)

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/hardware-orders \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "object": "list",
  • "url": "/v1/hardware-orders",
  • "data": [
    ]
}

Get hardware order

Returns a hardware order by ID, including embedded items.

Authorizations:
BearerAuthSessionAuth
path Parameters
order_id
required
string

Responses

Response Schema: application/json
id
string

Hardware order ID

status
string
Enum: "draft" "submitted" "fulfilled" "cancelled"

Order lifecycle status

Array of objects (HardwareOrderItem)

Line items in the order

created_at
string <date-time>
updated_at
string <date-time>

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/hardware-orders/%7Border_id%7D \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "draft",
  • "items": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update hardware order items

Replaces all items on a draft order. The order must be in draft status. Sends the complete desired state of items — existing items are replaced atomically.

Authorizations:
BearerAuthSessionAuth
path Parameters
order_id
required
string
Request Body schema: application/json
required
required
Array of objects non-empty
Array (non-empty)
hardware_catalog_id
required
string

ID of the hardware catalog item

quantity
required
integer [ 1 .. 100 ]

Responses

Response Schema: application/json
id
string

Hardware order ID

status
string
Enum: "draft" "submitted" "fulfilled" "cancelled"

Order lifecycle status

Array of objects (HardwareOrderItem)

Line items in the order

created_at
string <date-time>
updated_at
string <date-time>

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "draft",
  • "items": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Catalog

Hardware catalog listing. Returns available hardware items for selection during onboarding. Does not require account context.

List hardware catalog

Returns the list of active hardware items available for selection during onboarding. This endpoint does not require account context.

Authorizations:
BearerAuthSessionAuth

Responses

Response Schema: application/json
object
string
url
string
Array of objects (HardwareCatalogItem)

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/catalog \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "object": "list",
  • "url": "/v1/catalog",
  • "data": [
    ]
}

Audit Logs

Read-only access to audit trail entries

List audit logs

List audit log entries for an account with optional filtering. Results are returned in reverse chronological order (newest first).

Authorizations:
BearerAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

Number of objects to return. Defaults to 10. Maximum is 100.

event
string

Filter by event type (e.g., user.create, auth.denied). Supports comma-separated values.

resource
string

Filter by resource ID (exact match)

actor
string

Filter by actor ID (exact match)

outcome
string
Enum: "success" "failure" "denied"

Filter by outcome

ip_address
string

Filter by IP address

created_after
string <date-time>

Filter events created at or after this time (ISO 8601)

created_before
string <date-time>

Filter events created at or before this time (ISO 8601)

header Parameters
DialStack-Account
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

Account identifier for API key authentication. Not required when using session tokens (account is derived from JWT).

Responses

Response Schema: application/json
object
required
string (ListObject)
Value: "list"

String representing the object's type. Always "list" for list responses.

url
required
string (ListUrl)

The URL for accessing this list.

next_page_url
required
string or null (NextPageUrl)

URL to fetch the next page of results. If null, there are no more pages. The URL includes all necessary parameters including the pagination cursor.

previous_page_url
required
string or null (PreviousPageUrl)

URL to fetch the previous page of results. If null, this is the first page. The URL includes all necessary parameters including the pagination cursor.

required
Array of objects (AuditLogEntry)

Request samples 

curl -X GET \
  'https://api.dialstack.ai/v1/audit-logs?limit=10&event=SOME_STRING_VALUE&resource=SOME_STRING_VALUE&actor=SOME_STRING_VALUE&outcome=SOME_STRING_VALUE&ip_address=SOME_STRING_VALUE&created_after=SOME_STRING_VALUE&created_before=SOME_STRING_VALUE' \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41'

Response samples

Content type
application/json
{
  • "object": "list",
  • "url": "/v1/accounts",
  • "next_page_url": "/v1/accounts?page=eyJzdGFydGluZ19hZnRlciI6ImFjY3RfMDFoMnhjZWpxdGYybmJyZXh4M3ZxamhwNDEiLCJsaW1pdCI6MTB9",
  • "previous_page_url": "/v1/accounts?page=eyJlbmRpbmdfYmVmb3JlIjoiYWNjdF8wMWgyeGNlanF0ZjJuYnJleHgzdnFqaHA0MSIsImxpbWl0IjoxMH0",
  • "data": [
    ]
}

Quality

Call quality metrics and device registration health. Aggregate MOS/packet-loss summaries, worst-call lookups, and live device registration state for monitoring and troubleshooting. Requires account context via DialStack-Account header or session token.

Get quality metrics summary

Returns aggregated call quality metrics for the account, including KPI averages (MOS, jitter, packet loss) and a time-bucketed series. MOS is computed using the ITU-T G.107 E-model.

Authorizations:
BearerAuthSessionAuth
query Parameters
from
required
string <date-time>

Start of time range (RFC 3339)

to
required
string <date-time>

End of time range (RFC 3339)

granularity
required
string
Enum: "hourly" "daily"

Time bucket granularity

Responses

Response Schema: application/json
object
Array of objects

Request samples 

curl -X GET \
  'https://api.dialstack.ai/v1/quality/summary?from=SOME_STRING_VALUE&to=SOME_STRING_VALUE&granularity=SOME_STRING_VALUE' \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "kpi": {
    },
  • "time_series": [
    ]
}

Get worst quality calls

Returns the calls with the lowest MOS scores in the given time range, sorted by MOS ascending (worst first). Limited to 90-day range.

Authorizations:
BearerAuthSessionAuth
query Parameters
from
required
string <date-time>

Start of time range (RFC 3339)

to
required
string <date-time>

End of time range (RFC 3339)

limit
integer <= 50
Default: 10

Maximum number of calls to return (default 10, max 50)

Responses

Response Schema: application/json
Array of objects
Array
id
string

Call record ID

started_at
string <date-time>
direction
string
Enum: "inbound" "outbound" "internal"
from_number
string
to_number
string
duration_seconds
integer
mos
number

MOS score (1.0–5.0)

jitter_ms
number
packet_loss_pct
number

Request samples 

curl -X GET \
  'https://api.dialstack.ai/v1/quality/worst-calls?from=SOME_STRING_VALUE&to=SOME_STRING_VALUE&limit=SOME_INTEGER_VALUE' \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "calls": [
    ]
}

Get device registration status

Returns the registration status of all endpoints in the account, including whether each device is currently online or offline and its public IP address when available.

Authorizations:
BearerAuthSessionAuth

Responses

Response Schema: application/json
Array of objects
Array
id
string

Endpoint ID

name
string or null

Endpoint display name

status
string
Enum: "online" "offline"

Current registration status

public_ip
string

Public IP address of the device (when online)

Request samples 

curl -X GET \
  https://api.dialstack.ai/v1/quality/device-registrations \
  -H 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "devices": [
    ]
}