Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Phone Call Handling API
description: "You can access information from Zoom with Zoom Phone APIs to build private services or public applications on the [Zoom App Marketplace](https://marketplace.zoom.us/).\n\n To learn how to get your credentials and create private or public applications, see Zoom APIs use [OAuth 2.0 authorization](https://developers.zoom.us/docs/integrations/oauth/). \n\n All endpoints are available through `https` at `api.zoom.us/v2/`. For instance, `https://api.zoom.us/v2/users/` returns all users on an account. You'll receive a `403` error message if you have not set up Zoom Phone."
termsOfService: https://zoom.us/docs/en-us/zoom_api_license_and_tou.html
contact:
name: Zoom Developers
url: https://developer.zoom.us/
version: '2'
servers:
- url: https://api.zoom.us/v2
tags:
- name: Call Handling
paths:
/phone/extension/{extensionId}/call_handling/settings:
get:
tags:
- Call Handling
summary: Get call handling settings
description: 'Returns information about a Zoom Phone call handling settings.
Call handling settings let you control how your system routes calls during business, closed, or holiday hours. For more information, read our [API guide](https://developers.zoom.us/docs/zoom-phone/call-handling/) or Zoom support article [Customizing call handling settings](https://support.zoom.us/hc/en-us/articles/360059966372-Customizing-call-handling-settings).
**Applicable to user, call queue, auto receptionist, or shared line group call handling at this time.**
**Prerequisites:**
* Pro or a higher account with Zoom Phone enabled
**Deprecation notice:** This API is planned for deprecation.
Use the resource-specific APIs instead:
* For user call handling settings, use `GET /phone/users/{userId}/call_handling/settings`.
* For common area call handling settings, use `GET /phone/common_areas/{commonAreaId}/call_handling/settings`.
* For auto receptionist call handling settings, use `GET /phone/auto_receptionists/{autoReceptionistId}/call_handling/settings`.
* For call queue call handling settings, use `GET /phone/call_queues/{callQueueId}/call_handling/settings`.
* For shared line group call handling settings, use `GET /phone/shared_line_groups/{sharedLineGroupId}/call_handling/settings`.
* For user profile, holiday hour, custom hour, or other user setting data, use `GET /phone/users/{userId}/settings`.
* For common area holiday hour, custom hour, or other setting data, use `GET /phone/common_areas/{commonAreaId}/settings`.
* For auto receptionist holiday hour, custom hour, or other setting data, use `GET /phone/auto_receptionists/{autoReceptionistId}/settings`.
* For call queue holiday hour, custom hour, or other setting data, use `GET /phone/call_queues/{callQueueId}/settings`.
* For shared line group holiday hour, custom hour, or other setting data, use `GET /phone/shared_line_groups/{sharedLineGroupId}/settings`.
**[Scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-overview/):** `phone:read:admin`
**[Granular Scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-overview/):** `phone:read:list_call_handling_settings:admin`
**[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `LIGHT`'
operationId: getCallHandling
parameters:
- name: extensionId
in: path
description: The extension ID.
required: true
schema:
type: string
example: nNGsNx2zRDyiIXWVI23FCQ
responses:
'200':
description: "**HTTP Status Code:** `200` \n OK"
content:
application/json:
schema:
type: object
properties:
business_hours:
type: array
description: The information about business hours settings.
items:
type: object
properties:
settings:
type: object
properties:
allow_callers_check_voicemail:
type: boolean
description: "`Note: This field is invalid and part of incorrect documentation. It is not included in the actual response.` \n\nWhether to allow the callers to check voicemails over a phone. Required only when the `call_not_answer_action` setting is set to `1` (Forward to a voicemail)."
example: true
deprecated: true
allow_members_to_reset:
type: boolean
description: 'This field allows queue members to set their own business hours. It allows queue members'' business hours to override the default hours of the call queue.
Required for `Call Queue custom_hours` sub-setting.'
example: true
audio_while_connecting:
type: object
properties:
id:
type: string
description: The audio-while-connecting prompt ID. If the audio was removed from the user's audio library, it's marked with a prefix (for example, `removed_vWby3OZaQlS1nAdmEAqgwA`). You can use this audio ID to get the audio information in [Get an audio item](https://marketplace.zoom.us/docs/api-reference/phone/methods#tag/Audio-Library/operation/GetAudioItem) API.
example: qPwtDrrcSua8O0_n0bDRDg
name:
type: string
description: The audio while connecting the prompt name.
example: Default
description: 'Returns the audio played when the inbound callers are waiting to be routed to the next available call queue member.
* empty char - default
* `ring_tone` - "Ring Tone" option
* `0` - disable
Returned only for the `Call Queue` `call_handling` sub-setting.'
call_distribution:
type: object
properties:
handle_multiple_calls:
type: boolean
description: 'The maximum number of calls that can be handled simultaneously is less than half of the total amount of available call queue members. Note that the first incoming call might not be answered first.
Returned only except `simultaneous` ring mode.'
example: true
ring_duration:
type: integer
description: "The ringing duration for each member:\n* `10` \n* `15` \n* `20` \n* `25` \n* `30` \n* `35` \n* `40` \n* `45` \n* `50` \n* `55` \n* `60` \n\nReturned only except `simultaneous` ring mode."
example: 10
enum:
- 10
- 15
- 20
- 25
- 30
- 35
- 40
- 45
- 50
- 55
- 60
ring_mode:
type: string
description: "The call distribution ring mode: \n* `simultaneous` \n* `sequential` \n* `rotating` \n* `longest_idle`"
example: simultaneous
enum:
- simultaneous
- sequential
- rotating
- longest_idle
skip_offline_device_phone_number:
type: boolean
description: "1. Devices with Zoom app or client not launched and mobile phone with screen locked will be skipped. \n\n2. Phone numbers added to user's call handling settings are skipped.\n\nReturned only except `simultaneous` ring mode."
example: true
description: "This option distributes incoming calls.\n\nIf `Sequential` or `Rotating` is selected, calls ring for a specific time before trying the next available queue member. \n\nReturned only for the `call_handling` sub-setting."
call_forwarding_settings:
type: array
description: The call forwarding settings. It returns only for the `call_forwarding` sub-setting.
items:
type: object
properties:
description:
type: string
description: The external phone number's description.
example: testNumber
enable:
type: boolean
description: Whether to receive a call.
example: true
id:
type: string
description: The call forwarding's ID.
example: qPvrfrrcrf843cdfvbDRDg
phone_number:
type: string
description: The external phone number in E164 format.
example: '+12058945565'
external_contact:
type: object
properties:
name:
type: string
description: The external contact's username or extension display name.
example: Johnson
email:
type: string
description: The external contact's email address.
example: example@example.com
external_contact_id:
type: string
description: The external contact's ID.
example: OJGi5xOFQPmrJbKg68-iWg
phone_numbers:
type: array
description: The external contact's phone numbers.
items:
type: string
example: '+12058945656'
call_not_answer_action:
type: integer
description: "`Note: This field is invalid and part of incorrect documentation. It is not included in the actual response.` \n\nThe action to take when a call is not answered: \n* `1` — Forward to a voicemail. \n* `2` — Forward to the user. \n* `4` — Forward to the common area. \n* `6` — Forward to the auto receptionist. \n* `7` — Forward to a call queue. \n* `8` — Forward to a shared line group. \n* `9` — Forward to an external contact. \n* `10` - Forward to a phone number. \n* `11` — Disconnect. \n* `12` — Play a message, then disconnect. \n* `13` - Forward to message. \n* `14` - Forward to interactive voice response (IVR). \n\nReturned only for the `call_handling` sub-setting."
example: 2
deprecated: true
enum:
- 1
- 2
- 4
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
connect_to_operator:
type: boolean
description: "`Note: This field is invalid and part of incorrect documentation. It is not included in the actual response.` \n\nWhether to allow callers to reach an operator. Returns only when `call_not_answer_action` is set to `1` (Forward to a voicemail)."
example: true
deprecated: true
custom_hours_settings:
type: array
description: The custom hours settings. It returns only for the `custom_hours` sub-setting.
items:
type: object
properties:
from:
type: string
description: The custom hours start time and `HH:mm` format.
example: 09:00
to:
type: string
description: The custom hours end time in `HH:mm` format.
example: '18:00'
type:
type: integer
description: "The type of custom hours: \n* `0` — Disabled. \n* `1` — 24 hours. \n* `2` — Customized hours."
example: 1
enum:
- 0
- 1
- 2
weekday:
type: integer
description: "The day of the week: \n* `1` — Sunday \n* `2` — Monday \n* `3` — Tuesday \n* `4` — Wednesday \n* `5` — Thursday \n* `6` — Friday \n* `7` — Saturday"
example: 5
enum:
- 1
- 2
- 3
- 4
- 5
- 6
- 7
greeting_prompt:
type: object
properties:
id:
type: string
description: "The greeting audio prompt ID. \n\n Options: empty char - default and `0` - disable \n\n If the audio was removed from the user's audio library, it's marked with a prefix, `removed_vWby3OZaQlS1nAdmEAqgwA` for example. You can use this audio ID to get the audio information in [Get an audio item](https://marketplace.zoom.us/docs/api-reference/phone/methods#tag/Audio-Library/operation/GetAudioItem) API. "
example: '0'
name:
type: string
description: The greeting audio prompt name.
example: test
description: 'The greeting audio prompt
Returns only for the `Call Queue` or `Auto Receptionist` `call_handling` sub-setting.'
max_call_in_queue:
type: integer
description: 'The maximum number of calls in queue.
Specify the maximum number of callers to place in the queue. When this number is exceeded, callers will be routed based on the overflow option. Up to 60.
Returned only for the `Call Queue` `call_handling` sub-setting.'
example: 5
max_wait_time:
type: integer
description: "The maximum wait time, in seconds, for `simultaneous` ring mode or the ring duration for each device for `sequential` ring mode: \n* `10` \n* `15` \n* `20` \n* `25` \n* `30` \n* `35` \n* `40` \n* `45` \n* `50` \n* `55` \n* `60` \n\nSpecify how long a caller waits in the queue. Once the wait time is exceeded, the caller is rerouted based on the overflow option for call queue`:\n* `10` \n* `15` \n* `20` \n* `25` \n* `30` \n* `35` \n* `40` \n* `45` \n* `50` \n* `55` \n* `60` \n* `120` \n* `180` \n* `240` \n* `300` \n* `600` \n* `900` \n* `1200` \n* `1500` \n* `1800` \n\nReturned only for the `call_handling` sub-setting."
example: 30
enum:
- 10
- 15
- 20
- 25
- 30
- 35
- 40
- 45
- 50
- 55
- 60
- 120
- 180
- 240
- 300
- 600
- 900
- 1200
- 1500
- 1800
music_on_hold:
type: object
properties:
id:
type: string
description: The music on hold prompt ID. If the audio was removed from the user's audio library, it's marked with a prefix, (for example, `removed_vWby3OZaQlS1nAdmEAqgwA`). You can use this audio ID to get the audio information in [Get an audio item](https://marketplace.zoom.us/docs/api-reference/phone/methods#tag/Audio-Library/operation/GetAudioItem) API.
example: fdsij3he89qj2-23uie
name:
type: string
description: The music on hold prompt name.
example: Default
description: 'The music on hold prompt. This field is an option to choose music for inbound callers when they''re placed on hold by a call queue member.
empty char - default and `0` - disable.
Returned only for the `Call Queue` `call_handling` sub-setting.'
receive_call:
type: boolean
description: "This field enables calls to be received during a current call. When enabled, call queue members can receive new incoming calls notification even on the call. \n\nReturned only for the `Call Queue` `call_handling` sub-setting."
example: true
require_press_1_before_connecting:
type: boolean
description: When a call is forwarded to a personal phone number, whether the user must press "1" before the call connects. This field helps to ensure missed calls do not reach to your personal voicemail. This field returns only for the `call_forwarding` sub-setting.
example: true
ring_mode:
type: string
description: "The call handling ring mode: \n* `simultaneous` \n* `sequential` \n\nReturned only for the `call_handling` sub-setting."
example: simultaneous
enum:
- simultaneous
- sequential
routing:
type: object
properties:
action:
type: integer
description: "The action to take when a call is not answered during Business Hours: \n* `1` — Forward to a Voicemail. Applicable to `User`, `Call Queue`, `Auto Receptionist`, or `Shared Line Group`. \n* `2` — Forward to the User. Applicable to `User`, `Call Queue`, `Auto Receptionist`, or `Shared Line Group`. \n* `3` — Forward to the Zoom Room. Applicable to `User`, `Call Queue`, `Auto Receptionist`, or `Shared Line Group`. \n* `4` — Forward to the Common Area. Applicable to `User`, `Call Queue`, `Auto Receptionist`, or `Shared Line Group`. \n* `5` — Forward to the Cisco/Polycom Room. Applicable to `User`, `Call Queue`, `Auto Receptionist`, or `Shared Line Group`. \n* `6` — Forward to the Auto Receptionist. Applicable to `User`, `Call Queue`, `Auto Receptionist`, or `Shared Line Group`. \n* `7` — Forward to a Call Queue. Applicable to `User`, `Call Queue`, `Auto Receptionist`, or `Shared Line Group`. \n* `8` — Forward to a Shared Line Group. Applicable to `User`, `Call Queue`, `Auto Receptionist`, or `Shared Line Group`. \n* `9` — Forward to an External Contact. Applicable to `User`, `Call Queue`, `Auto Receptionist`, or `Shared Line Group`. \n* `10` - Forward to a Phone Number. Applicable to `User`, `Call Queue`, `Auto Receptionist`, or `Shared Line Group`. \n* `11` — Disconnect. Applicable to `User`, `Call Queue`, or `Shared Line Group`. \n* `12` — Play a message, then disconnect. Applicable to `User`, `Call Queue`, `Auto Receptionist`, or `Shared Line Group` \n* `14` - Forward to an Interactive Voice Response (IVR). Applicable to `Auto Receptionist`. \n* `15` — Forward to a Partner Contact Center. Applicable to `Auto Receptionist`. \n* `18` — Forward to Microsoft Teams Resource Account. Required the license of Zoom Phone for Microsoft Teams. Applicable to `Call queue`, `Auto Receptionist`, or `Shared Line group`. \n* `19` — Forward to a Zoom Contact Center. Required Zoom Contact Center license. Applicable to `Call Queue`, `Auto Receptionist`, or `Shared Line Group`."
example: 1
enum:
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 14
- 15
- 18
- 19
forward_to:
type: object
properties:
display_name:
type: string
description: The extension's name.
example: api_ta_test
extension_id:
type: string
description: The extension ID.
example: jN9mb38lQTaMgxUq3Nd6ow
extension_number:
type: integer
description: The extension number.
format: int64
example: 101014
extension_type:
type: string
description: "The type of extension: \n* `user` \n* `autoReceptionist` \n* `callQueue`"
example: user
enum:
- user
- autoReceptionist
- callQueue
- commonArea
id:
type: string
description: The ID of the extension for `user`, `autoReceptionist`, `device`, or `callQueue`.
example: DYHrdpjrS3uaOf7dPkkg8w
phone_number:
type: string
description: "The extension's phone number or forward to an external number, in [E.164 format](https://en.wikipedia.org/wiki/E.164) format. \n\nThis field is only available in the following scenarios: \n* Secnario 1: When `action` in the `routing` section is set to `10` (Forward to Phone number/External number) for unanswered calls, this field is used to display the specific Phone number/External number to which the call will be forwarded. This scenario applies to `User`, `Auto Receptionist`, `Call Queue` and `Shared Line Group`."
example: '+18889843519'
description:
type: string
description: "This field forwards to an external number description. \n\nThis field is only available in the following scenarios: \n* Secnario 1: When `action` in the `routing` section is set to `10` (Forward to Phone number/External number) for unanswered calls, this field is used to display the specific Phone number/External number to which the call will be forwarded. This scenario applies to `User`, `Auto Receptionist`, `Call Queue` and `Shared Line Group`."
example: forward to phone number +18889843519.
voicemail_greeting:
type: object
properties:
id:
type: string
description: "The voicemail greeting audio prompt ID. \n\n Options: empty char - default"
example: b_fFF75hRgCtzG7Dw7wQgQ
name:
type: string
description: The voicemail greeting audio prompt name.
example: Voicemail greeting
description: The voicemail greeting prompt. It returns only when the `action` in the `routing` section is set to `1` (Forward to a voicemail) for the `Call Queue` or `Auto Receptionist` `call_handling` sub-setting.
zcc_phone_number:
type: string
description: "The Zoom Contact Center phone number to which the call is forwarded. \n\nThis field is only available in the following scenarios: \n* Secnario 1: When `action` in the `routing` section is set to `19` (Forward to a Zoom Contact Center) for unanswered calls, this field is used to display the specific Zoom Contact Center to which the call will be forwarded. This scenario applies to `Auto Receptionist`, `Call Queue` and `Shared Line Group`."
example: '12055903036'
zcc_phone_number_display_name:
type: string
description: "The display name of the Zoom Contact Center phone number to which the call is forwarded. \n\nThis field is only available in the following scenarios: \n* Secnario 1: When `action` in the `routing` section is set to `19` (Forward to a Zoom Contact Center) for unanswered calls, this field is used to display the specific Zoom Contact Center to which the call will be forwarded. This scenario applies to `Auto Receptionist`, `Call Queue` and `Shared Line Group`."
example: Display name - (205) 690-3036(American English)
partner_contact_center_id:
type: string
description: "The ID of the Partner Contact Center to which the call is forwarded. \n\nThis field is only available in the following scenarios: \n* Secnario 1: When `action` in the `routing` section is set to `15` (Forward to a Partner Contact Center) for unanswered calls, this field is used to display the specific Partner Contact Center to which the call will be forwarded. This scenario applies to `Auto Receptionist`."
example: 0Qa7FFTfR0CgzpgwUrcxtQ
pcc_phone_number_display_name:
type: string
description: "The display name of the Partner Contact Center to which the call is forwarded. \n\nThis field is only available in the following scenarios: \n* Secnario 1: When `action` in the `routing` section is set to `15` (Forward to a Partner Contact Center) for unanswered calls, this field is used to display the specific Partner Contact Center to which the call will be forwarded. This scenario applies to `Auto Receptionist`."
example: Test contact center
teams_app_id:
type: string
description: "The ID of the Microsoft Teams Voice App to which the call is forwarded. \n\nThis field is only available in the following scenarios: \n* Secnario 1: When `action` in the `routing` section is set to `18` (Forward to Microsoft Teams Resource Account) for unanswered calls, this field is used to display the specific Microsoft Teams Voice App to which the call will be forwarded. This scenario applies to `Auto Receptionist`, `Call Queue` and `Shared Line Group`."
example: wgYRHE6ITJOZmV6DBvoyZw
teams_voice_app_name:
type: string
description: "The display name of the Microsoft Teams Voice App to which the call is forwarded. \n\nThis field is only available in the following scenarios: \n* Secnario 1: When `action` in the `routing` section is set to `18` (Forward to Microsoft Teams Resource Account) for unanswered calls, this field is used to display the specific Microsoft Teams Voice App to which the call will be forwarded. This scenario applies to `Auto Receptionist`, `Call Queue` and `Shared Line Group`."
example: Test Teams app
description: "The information about the call forwarding target. \n\nThis field is only available in the foll
# --- truncated at 32 KB (203 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zoom-phone/refs/heads/main/openapi/zoom-phone-call-handling-api-openapi.yml