Skip to content

Update a studio

PATCH
/v1/studios/{studio}
curl --request PATCH \
--url https://api.caller9.app/v1/studios/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "name": "example", "cid_display_name": "example", "ai_assistant_id": "example", "cid_number_guid": "example", "busy_all": true, "auto_dnd_when_empty": true, "ring_time": 1, "hotline_ring_time": 1, "ring_timeout_action": "none", "voicemail_greeting_type": "tts", "voicemail_greeting_tts": "example", "voicemail_greeting_voice": "example", "voicemail_max_seconds": 1, "voicemail_record_message": true, "voicemail_email": "hello@example.com", "email_voicemails_enabled": true, "delete_after_email": true, "forward_dest_type": "sip", "forward_sip_address": "example", "forward_phone_number": "example", "screen_all_station_name": "example", "screen_all_show_description": "example", "screen_all_station_location": "example", "ai_screening_enabled": true, "screen_all": true, "contest_enabled": true, "contest_target": 1, "contest_backups": 1, "contest_post_timeout_secs": 1, "moh_mode": "library", "moh_library_guid": "example", "hybrid_count": 1 }'

Partially updates studio settings. Only the fields present in the body are changed; at least one updatable field is required. Requires a full-access key.

Notable behaviors:

  • cid_display_name is CNAM-normalized (uppercased, only letters/digits/periods/commas/spaces, must start with a letter, truncated to 15 characters).
  • Changing hybrid_count provisions or removes the hybrid_N SIP endpoints (new credentials are shown via GET /v1/studios/{studio}/sip-endpoints).
  • Switching moh_mode to pgm provisions a hold SIP endpoint; switching away from pgm removes it (re-enabling later issues new credentials). moh_mode: file requires a file uploaded first via PUT /v1/studios/{studio}/moh.
  • Setting ring_timeout_action: forward requires a forward destination (in this request or already saved) and a plan that includes call forwarding.
  • Enabling ai_screening_enabled requires the Premium plan and an ai_assistant_id; disabling it also turns screen_all off. Disabling contest_enabled also stops any armed contest.
  • Enabling email_voicemails_enabled requires voicemail_email to be set.
  • Changes to busy_all / screen_all are pushed live to all open operator dashboards.
studio
required
string format: uuid

Studio ID (UUID).

Media typeapplication/json
object
>= 1 properties
name
string
<= 255 characters
cid_display_name

Outbound caller ID name. CNAM-normalized; must be at least 2 characters after normalization (or empty).

string
<= 255 characters
ai_assistant_id

ID of the AI assistant used for screening (see the AI assistants endpoints).

string
<= 255 characters
cid_number_guid

Number (owned by the same organization) used as outbound caller ID. null or "" clears it.

string | null
busy_all

Busy / Do-Not-Disturb — send every inbound call to voicemail.

boolean
auto_dnd_when_empty

Automatically behave as Do-Not-Disturb when no operator has the studio open.

boolean
ring_time

Seconds a queued call rings before the ring-timeout action.

integer
>= 5 <= 60
hotline_ring_time

Ring time for hotline-number calls, in seconds.

integer
>= 5 <= 60
ring_timeout_action
string
Allowed values: none voicemail forward
voicemail_greeting_type

Switching to tts discards any uploaded greeting file. Switching to file is done by uploading via PUT /v1/studios/{studio}/voicemail-greeting.

string
Allowed values: tts file
voicemail_greeting_tts

Text-to-speech greeting text.

string
<= 2000 characters
voicemail_greeting_voice

TTS voice ID (see the TTS voices endpoint). null or "" resets to the platform default voice.

string | null
<= 200 characters
voicemail_max_seconds
integer
>= 5 <= 600
voicemail_record_message

Whether to record a message after the greeting (false = greeting only).

boolean
voicemail_email

Address voicemails are emailed to. null or "" clears it.

string | null format: email
email_voicemails_enabled
boolean
delete_after_email

Delete the voicemail recording after it has been emailed.

boolean
forward_dest_type

Ring-timeout forwarding destination type. Must be sent together with the matching address field. null clears the destination.

string | null
Allowed values: sip phone
forward_sip_address

Required when forward_dest_type is sip; form sip:user@host.

string
<= 255 characters
forward_phone_number

Required when forward_dest_type is phone; a US or Canadian number, normalized to E.164.

string
<= 32 characters
screen_all_station_name

Station name provided to the AI screener.

string
<= 500 characters
screen_all_show_description

Show description provided to the AI screener.

string
<= 2000 characters
screen_all_station_location

Station location provided to the AI screener.

string
<= 500 characters
ai_screening_enabled

Capability gate for AI screening. Premium only; requires an AI assistant.

boolean
screen_all

Screen every inbound call with the AI assistant. Returns 409 if AI screening is not enabled.

boolean
contest_enabled

Capability gate for Contest Mode.

boolean
contest_target

Default winning caller number.

integer
>= 1 <= 110
contest_backups

Default number of backup winners after the target caller.

integer
<= 100
contest_post_timeout_secs

Default length of the post-contest window, in seconds.

integer
>= 10 <= 3600
moh_mode

Music on Hold source — platform library track, custom uploaded file, or a live program feed over SIP.

string
Allowed values: library file pgm
moh_library_guid

Library entry from GET /v1/studios/{studio}/moh-library. null selects the platform default.

string | null
hybrid_count

Number of on-air hybrid SIP endpoints. Basic and Demo plans are limited to 1.

integer
<= 4

The updated studio.

Media typeapplication/json
object
studio
required

A studio and its configuration. Boolean settings are returned as integers (0 / 1). Returned by GET/PATCH /v1/studios/{studio} and by the organization studio list/create endpoints.

object
guid
required

Studio ID.

string
name
required
string
organization_guid
required

Owning organization ID.

string
cid_number_guid
required

Number used as outbound caller ID, if set.

string | null
cid_display_name
required

Outbound caller ID name (CNAM-normalized).

string
<= 15 characters
busy_all
required

Busy / Do-Not-Disturb is on.

integer
Allowed values: 0 1
auto_dnd_when_empty
required

Act as Do-Not-Disturb when no operator has the studio open.

integer
Allowed values: 0 1
ring_time
required

Seconds before the ring-timeout action (5–60).

integer
hotline_ring_time
required

Ring time for hotline calls, in seconds (5–60).

integer
ai_assistant_id
required

AI assistant used for screening.

string | null
ai_screening_enabled
required

AI screening capability is enabled.

integer
Allowed values: 0 1
hybrid_count
required

Number of on-air hybrid SIP endpoints.

integer
<= 4
screen_all
required

Every inbound call is screened by the AI assistant.

integer
Allowed values: 0 1
screen_all_station_name
required
string
screen_all_show_description
required
string
screen_all_station_location
required
string
contest_enabled
required

Contest Mode capability is enabled.

integer
Allowed values: 0 1
contest_mode
required

A contest is currently armed.

integer
Allowed values: 0 1
contest_target
required

Default winning caller number (1–110).

integer
contest_backups
required

Default number of backup winners (0–100).

integer
contest_post_timeout_secs
required

Default post-contest window in seconds (10–3600).

integer
ring_timeout_action
required
string
Allowed values: none voicemail forward
voicemail_greeting_type
required
string
Allowed values: tts file
voicemail_greeting_tts
required

Text-to-speech greeting text.

string
voicemail_greeting_voice
required

TTS voice ID; null means the platform default voice.

string | null
voicemail_greeting_r2_key
required

Storage key of the uploaded greeting file, if any.

string | null
voicemail_tts_r2_key
required

Storage key of the cached synthesized TTS greeting, if any.

string | null
voicemail_max_seconds
required

Maximum voicemail length in seconds (5–600).

integer
voicemail_record_message
required

Record a message after the greeting.

integer
Allowed values: 0 1
email_voicemails_enabled
required
integer
Allowed values: 0 1
voicemail_email
required
string | null
delete_after_email
required
integer
Allowed values: 0 1
forward_dest_type
required

Ring-timeout forwarding destination type.

string | null
Allowed values: sip phone
forward_sip_address
required

Set when forward_dest_type is sip.

string | null
forward_phone_number
required

E.164 number; set when forward_dest_type is phone.

string | null
moh_mode
required
string
Allowed values: library file pgm
moh_library_guid
required

Selected library track; null means the platform default.

string | null
moh_r2_key
required

Storage key of the uploaded custom Music on Hold file, if any.

string | null
created_at
required

Creation timestamp (ISO 8601).

string
updated_at
required

Last update timestamp (ISO 8601).

string
deleted_at
required

Always null for studios returned by the API.

string | null

Example

{
"studio": {
"busy_all": 0,
"auto_dnd_when_empty": 0,
"ai_screening_enabled": 0,
"screen_all": 0,
"contest_enabled": 0,
"contest_mode": 0,
"ring_timeout_action": "none",
"voicemail_greeting_type": "tts",
"voicemail_record_message": 0,
"email_voicemails_enabled": 0,
"delete_after_email": 0,
"forward_dest_type": "sip",
"moh_mode": "library"
}
}

The request was invalid.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

Missing, invalid, expired or revoked API key.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

The key isn’t allowed to do this (e.g. a read-only key making a change).

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

Not found, or belongs to another organization.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

Plan limit reached (ai_screening, call forwarding), or screen_all enabled without AI screening.

Media typeapplication/json
One of:
object
error
required
string
Allowed value: plan_limit
limit
required

Which cap was hit, e.g. studios, numbers, ai_screening, trunk_channels.

string
message
required
string

Example

{
"error": "plan_limit"
}

Too many requests for this API key. Retry after Retry-After seconds.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}
Retry-After
integer

Seconds until the rate-limit window resets.