Update a studio
const url = 'https://api.caller9.app/v1/studios/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0';const options = { method: 'PATCH', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"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}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}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_nameis CNAM-normalized (uppercased, only letters/digits/periods/commas/spaces, must start with a letter, truncated to 15 characters).- Changing
hybrid_countprovisions or removes thehybrid_NSIP endpoints (new credentials are shown viaGET /v1/studios/{studio}/sip-endpoints). - Switching
moh_modetopgmprovisions aholdSIP endpoint; switching away frompgmremoves it (re-enabling later issues new credentials).moh_mode: filerequires a file uploaded first viaPUT /v1/studios/{studio}/moh. - Setting
ring_timeout_action: forwardrequires a forward destination (in this request or already saved) and a plan that includes call forwarding. - Enabling
ai_screening_enabledrequires the Premium plan and anai_assistant_id; disabling it also turnsscreen_alloff. Disablingcontest_enabledalso stops any armed contest. - Enabling
email_voicemails_enabledrequiresvoicemail_emailto be set. - Changes to
busy_all/screen_allare pushed live to all open operator dashboards.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Studio ID (UUID).
Request Bodyrequired
Section titled “Request Bodyrequired”object
Outbound caller ID name. CNAM-normalized; must be at least 2 characters after normalization (or empty).
ID of the AI assistant used for screening (see the AI assistants endpoints).
Number (owned by the same organization) used as outbound caller ID. null or "" clears it.
Busy / Do-Not-Disturb — send every inbound call to voicemail.
Automatically behave as Do-Not-Disturb when no operator has the studio open.
Seconds a queued call rings before the ring-timeout action.
Ring time for hotline-number calls, in seconds.
Switching to tts discards any uploaded greeting file. Switching to file is done by uploading via PUT /v1/studios/{studio}/voicemail-greeting.
Text-to-speech greeting text.
TTS voice ID (see the TTS voices endpoint). null or "" resets to the platform default voice.
Whether to record a message after the greeting (false = greeting only).
Address voicemails are emailed to. null or "" clears it.
Delete the voicemail recording after it has been emailed.
Ring-timeout forwarding destination type. Must be sent together with the matching address field. null clears the destination.
Required when forward_dest_type is sip; form sip:user@host.
Required when forward_dest_type is phone; a US or Canadian number, normalized to E.164.
Station name provided to the AI screener.
Show description provided to the AI screener.
Station location provided to the AI screener.
Capability gate for AI screening. Premium only; requires an AI assistant.
Screen every inbound call with the AI assistant. Returns 409 if AI screening is not enabled.
Capability gate for Contest Mode.
Default winning caller number.
Default number of backup winners after the target caller.
Default length of the post-contest window, in seconds.
Music on Hold source — platform library track, custom uploaded file, or a live program feed over SIP.
Library entry from GET /v1/studios/{studio}/moh-library. null selects the platform default.
Number of on-air hybrid SIP endpoints. Basic and Demo plans are limited to 1.
Responses
Section titled “Responses”The updated studio.
object
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
Studio ID.
Owning organization ID.
Number used as outbound caller ID, if set.
Outbound caller ID name (CNAM-normalized).
Busy / Do-Not-Disturb is on.
Act as Do-Not-Disturb when no operator has the studio open.
Seconds before the ring-timeout action (5–60).
Ring time for hotline calls, in seconds (5–60).
AI assistant used for screening.
AI screening capability is enabled.
Number of on-air hybrid SIP endpoints.
Every inbound call is screened by the AI assistant.
Contest Mode capability is enabled.
A contest is currently armed.
Default winning caller number (1–110).
Default number of backup winners (0–100).
Default post-contest window in seconds (10–3600).
Text-to-speech greeting text.
TTS voice ID; null means the platform default voice.
Storage key of the uploaded greeting file, if any.
Storage key of the cached synthesized TTS greeting, if any.
Maximum voicemail length in seconds (5–600).
Record a message after the greeting.
Ring-timeout forwarding destination type.
Set when forward_dest_type is sip.
E.164 number; set when forward_dest_type is phone.
Selected library track; null means the platform default.
Storage key of the uploaded custom Music on Hold file, if any.
Creation timestamp (ISO 8601).
Last update timestamp (ISO 8601).
Always null for studios returned by the API.
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.
object
Human-readable error message.
Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).
Example generated
{ "error": "example", "code": "example"}Missing, invalid, expired or revoked API key.
object
Human-readable error message.
Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).
Example generated
{ "error": "example", "code": "example"}The key isn’t allowed to do this (e.g. a read-only key making a change).
object
Human-readable error message.
Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).
Example generated
{ "error": "example", "code": "example"}Not found, or belongs to another organization.
object
Human-readable error message.
Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).
Example generated
{ "error": "example", "code": "example"}Plan limit reached (ai_screening, call forwarding), or screen_all enabled without AI screening.
object
Which cap was hit, e.g. studios, numbers, ai_screening, trunk_channels.
object
Human-readable error message.
Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).
Example
{ "error": "plan_limit"}Too many requests for this API key. Retry after Retry-After seconds.
object
Human-readable error message.
Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).
Example generated
{ "error": "example", "code": "example"}Headers
Section titled “Headers”Seconds until the rate-limit window resets.