Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Phone IVR 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: IVR
paths:
/phone/auto_receptionists/{autoReceptionistId}/ivr:
get:
tags:
- IVR
summary: Get auto receptionist IVR
description: "Returns an [interactive voice response (IVR) system](https://support.zoom.us/hc/en-us/articles/360038601971) of the specified auto receptionist.\n\n**Prerequisites:** \n* A Business or Enterprise account \n* A Zoom Phone license\n\n**[Scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-overview/):** `phone:read:admin`\n\n**[Granular Scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-overview/):** `phone:read:auto_receptionist_ivr:admin`\n\n**[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `LIGHT`"
operationId: getAutoReceptionistIVR
parameters:
- name: autoReceptionistId
in: path
description: The unique identifier of the auto receptionist. You can retrieve it from the [List Phone Sites](https://marketplace.zoom.us/docs/api-reference/phone/methods#operation/listPhoneSites) API.
required: true
schema:
type: string
example: HpgmeAcmSVK-UY-0RxDcfg
- name: hours_type
in: query
description: The type of query hours.
required: false
schema:
type: string
example: business_hours
default: business_hours
enum:
- business_hours
- closed_hours
- holiday_hours
- break_hours
- name: holiday_id
in: query
description: The auto receptionist holiday hours ID. If both `holiday_id` and `hours_type` are passed, `holiday_id` has the highest priority and `hours_type` is ignored.
required: false
schema:
type: string
example: YpLBylKbQKe1vEB1iSGatQ
- name: break_id
in: query
description: The auto receptionist break hours ID. Required when `hours_type` is `break_hours`. If `holiday_id` is also passed, `holiday_id` takes precedence.
required: false
schema:
type: string
example: ULfeE4mgSImyelNmTekUfg
responses:
'200':
description: "**HTTP Status Code:** `200` \n Get an interactive voice response (IVR) system of an auto receptionist."
content:
application/json:
schema:
type: object
properties:
audio_prompt:
type: object
properties:
id:
type: string
description: The audio prompt file ID. If the audio was removed from the user's audio library, it will be marked with a prefix, `removed_vWby3OZaQlS1nAdmEAqgwA` for example. You can still use this audio ID to get the audio information in the [Get an audio item](https://marketplace.zoom.us/docs/api-reference/phone/methods#tag/Audio-Library/operation/GetAudioItem) API.
example: yCT14TwySDGVUypVlKNEyA
name:
type: string
description: The audio prompt's file name.
example: example.mp3
description: The audio prompt played to the caller when the IVR is reached.
caller_enters_no_action:
type: object
properties:
action:
type: integer
description: "The action when a caller enters no action after the prompt played. \n \n`-1` Disconnect the call \n \n`2` Forward to the user\n \n `4` Forward to the common area\n \n `5` Forward to Cisco/Polycom Room\n \n `6` Forward to the auto receptionist\n \n `7` Forward to the call queue\n \n `8` Forward to the shared line group\n\n `9` Forward to external contacts \n\n `10` Forward to a phone number\n\n `12` Play a message, then disconnect\n \n `15` Forward to the partner contact center\n\n `18` Forward to Microsoft Teams Resource Account. Required the license of Zoom Phone for Microsoft Teams. \n\n `19` Forward to the Zoom Contact Center voice flow. Required Zoom Contact Center license.\n\n `24` Forward to the ZVA(Zoom Virtual Agent) Receptionist\n\n `25` Forward to the Third-party agent\n"
example: 15
caller_no_input_timeout:
type: integer
description: The number of seconds to wait for the caller's input (DTMF keypad or voice) after the prompt plays before the IVR takes the no-action `action`. Applies only when `allow_callers_to_navigate_ivr.enable` is `true`; otherwise this value is ignored.
example: 3
default: 3
enum:
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
audio_prompt_repeat:
type: integer
description: The number of times to repeat the audio prompt.
example: 3
enum:
- 1
- 2
- 3
- 4
- 5
voicemail_greeting:
type: object
properties:
id:
type: string
description: The voicemail greeting file ID. If the audio was removed from the user's audio library, it will be marked with a prefix, `removed_vWby3OZaQlS1nAdmEAqgwA` for example. You can still use this audio ID to get the audio information in the [Get an audio item](https://marketplace.zoom.us/docs/api-reference/phone/methods#tag/Audio-Library/operation/GetAudioItem) API.
example: j2IsurWLRR-yWcbNGqPnaA
name:
type: string
description: The voicemail greeting's file name.
example: custom.wav
description: The voicemail greeting.
forward_to:
type: object
properties:
display_name:
type: string
description: The name of the display.
example: ZOOM_API Test
extension_id:
type: string
description: The extension ID or partner contact center setting ID.
example: z97zV9NsSoa846i-ag3uEw
extension_number:
type: string
description: The extension number.
example: '101021'
id:
type: string
description: The user, common area, Zoom Room, Cisco/Polycom room, auto receptionist, call queue, or shared line group ID.
example: EVqEKnrMRWyPr705Fk5h2w
phone_number:
type: string
description: "The 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* When `action` is set to `10` (Forward to Phone number/External number), this field is used to display the specific Phone number/External number to which the call will be forwarded. \n* When `action` is set to `19` (Forward to the Zoom Contact Center voice flow), this field is used to display the specific Zoom Contact Center number to which the call will be forwarded. \n"
example: '+18889843519'
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* When `action` is set to `18` (Forward to Microsoft Teams Resource Account), this field is used to display the specific Microsoft Teams Voice App to which the call will be forwarded. "
example: oB18huSERjqbzrsyL2bD5w
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* When `action` is set to `15` (Forward to a Partner Contact Center), this field is used to display the specific Partner Contact Center to which the call will be forwarded."
example: 0za4SO7OQ5mxeHEP8nHvGg
zva_receptionist_id:
type: string
description: "The ID of the ZVA(Zoom Virtual Agent) Receptionist to which the call is forwarded. \n\nThis field is only available in the following scenarios: \n* When `action` is set to `24` (Forward to the ZVA Receptionist), this field is used to display the specific ZVA Receptionist to which the call will be forwarded. "
example: 6uv8qMMDShm6OGgFTrQPbA
third_party_agent_id:
type: string
description: "The ID of the Third-party agent to which the call is forwarded. \n\nThis field is only available in the following scenarios: \n* When `action` is set to `25` (Forward to the Third-party agent), this field is used to display the specific Third-party agent to which the call will be forwarded. \n"
example: T0x6LuR4TBKWFY6_ulxaOQ
external_contact_id:
type: string
description: "The ID of the external contact to which the call is forwarded. \n\nThis field is only available in the following scenarios: \n* When `action` is set to `9` (Forward to external contacts), this field is used to display the specific external contact to which the call will be forwarded. \n"
example: OJGi5xOFQPmrJbKg68-iWg
description: The forward target for the no-action `action`.
description: The action if the caller enters no action after the prompt plays.
key_actions:
maxItems: 50
type: array
description: The IVR routing options.
items:
type: object
properties:
action:
type: integer
description: "The action after clicking the key. \n\nFor all keys (`0`-`9`, * or #)\n \n`100` Leave voicemail to the current extension \n \n`200` Leave voicemail to the user \n \n`300` Leave voicemail to the auto receptionist \n \n`400` Leave voicemail to the call queue \n \n`500` Leave voicemail to the shared line group \n \n`2` Forward to the user \n \n`3` Forward to Zoom Room \n \n`4` Forward to the common area \n \n`5` Forward to Cisco/Polycom Room \n \n`6` Forward to the auto receptionist \n \n`7` Forward to the call queue \n \n`8` Forward to the shared line group \n \n`9` Forward to external contacts \n \n`10` Forward to a phone number \n\n`12` Play a message, then disconnect\n \n`15` Forward to the partner contact center \n \n`16` Forward to the meeting service \n \n`17` Forward to the meeting service number \n\n`18` Forward to Microsoft Teams Resource Account. Required the license of Zoom Phone for Microsoft Teams. \n\n`19` Forward to the zoom contact center voice flow. Required Zoom Contact Center license.\n\n`24` Forward to the ZVA(Zoom Virtual Agent) Receptionist\n\n`25` Forward to the Third-party agent\n\n`27` Play a message, then repeat menu greeting\n\n`28` Play a message, then return to root menu\n\n`29` Play a message, then return to previous menu\n\n \n`-1` Disabled\n\nFor key `0`-`9` only:\n\n`26` Dial by Name. \n**Note**: The value of `action = 26` (`Dial by Name`) is available only when **Dial by Name Directory** is enabled. For multi-site accounts, this is checked at the site level via [Get a phone site setting](https://developers.zoom.us/docs/api/phone/#tag/sites/get/phone/sites/{siteId}/settings/{settingType}) with `settingType=dial_by_name`; otherwise, it follows the account-level setting.\n\nFor key * or # only:\n \n`21` Repeat menu greeting \n \n`22` Return to the root menu \n \n`23` Return to the previous menu "
example: 200
key:
type: string
description: 'The key. The following values are supported: numeric(''0''-''9''), *, #.'
example: '0'
target:
type: object
properties:
display_name:
type: string
description: The name of the display.
example: ZOOM_API Test
extension_id:
type: string
description: The extension ID or partner contact center setting ID.
example: TO586CYlQFC_WCUvPRXytA
extension_number:
type: string
description: The extension number.
example: '101002'
id:
type: string
description: The user, common area, Zoom Room, Cisco/Polycom room, auto receptionist, call queue, or shared line group ID.
example: oG_nYRFuTJiY1tu0Fur_4Q
phone_number:
type: string
description: "The 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* When `action` is set to `10` (Forward to Phone number/External number), this field is used to display the specific Phone number/External number to which the call will be forwarded. \n* When `action` is set to `19` (Forward to the Zoom Contact Center voice flow), this field is used to display the specific Zoom Contact Center number to which the call will be forwarded. \n"
example: '+12055437350'
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* When `action` is set to `18` (Forward to Microsoft Teams Resource Account), this field is used to display the specific Microsoft Teams Voice App to which the call will be forwarded. "
example: oB18huSERjqbzrsyL2bD5w
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* When `action` is set to `15` (Forward to a Partner Contact Center), this field is used to display the specific Partner Contact Center to which the call will be forwarded."
example: 0za4SO7OQ5mxeHEP8nHvGg
zva_receptionist_id:
type: string
description: "The ID of the ZVA(Zoom Virtual Agent) Receptionist to which the call is forwarded. \n\nThis field is only available in the following scenarios: \n* When `action` is set to `24` (Forward to the ZVA Receptionist), this field is used to display the specific ZVA Receptionist to which the call will be forwarded. "
example: 6uv8qMMDShm6OGgFTrQPbA
third_party_agent_id:
type: string
description: "The ID of the Third-party agent to which the call is forwarded. \n\nThis field is only available in the following scenarios: \n* When `action` is set to `25` (Forward to the Third-party agent), this field is used to display the specific Third-party agent to which the call will be forwarded. \n"
example: T0x6LuR4TBKWFY6_ulxaOQ
external_contact_id:
type: string
description: "The ID of the external contact to which the call is forwarded. \n\nThis field is only available in the following scenarios: \n* When `action` is set to `9` (Forward to external contacts), this field is used to display the specific external contact to which the call will be forwarded. \n"
example: OJGi5xOFQPmrJbKg68-iWg
description: Routes to an extension, phone number, or a contact center. The relevant ID field is required based on the selected `action`.
voicemail_greeting:
type: object
properties:
id:
type: string
description: The voicemail greeting file ID. If the audio was removed from the user's audio library, it will be marked with a prefix, `removed_vWby3OZaQlS1nAdmEAqgwA` for example. You can still use this audio ID to get the audio information in the [Get an audio item](https://marketplace.zoom.us/docs/api-reference/phone/methods#tag/Audio-Library/operation/GetAudioItem) API.
example: j2IsurWLRR-yWcbNGqPnaA
name:
type: string
description: The voicemail greeting's file name.
example: custom.wav
description: The voicemail greeting.
allow_callers_to_navigate_ivr:
type: object
properties:
enable:
type: boolean
description: Whether callers are allowed to navigate the IVR menu by voice in addition to DTMF keypad input. When `true`, the Zoom Phone IVR engine performs speech-to-intent matching against the configured `key_actions` and routes the call accordingly.
example: true
default: false
voice_input_confidence_score:
type: string
description: The minimum speech-recognition confidence threshold required to accept a voice input as a valid IVR selection.
example: low
default: high
enum:
- low
- medium
- high
description: Configures whether callers can navigate the IVR menu by voice in addition to DTMF keypad input.
allow_dialing_by_extension:
type: boolean
description: Whether to allow callers to dial an extension to reach users, common areas, call queues, auto receptionists, and shared line groups on this account.
example: true
default: true
'400':
description: "**HTTP Status Code:** `400` <br>\n Bad Request \n\n **Error Code:** `400` <br>\n Auto Receptionist does not exist: {0}.\nHoliday hours handling does not exist: {0}.\nBreak hours handling does not exist: {0}. <br>\n"
'429':
description: "**HTTP Status Code:** `429` <br>\n Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/). \n\n "
security:
- openapi_oauth:
- phone:read:admin
- phone:read:auto_receptionist_ivr:admin
openapi_authorization: []
x-extensions:
x-permissions: []
x-macro-scopes:
- phone:read:admin
x-granular-scopes:
- phone:read:auto_receptionist_ivr:admin
patch:
tags:
- IVR
summary: Update auto receptionist IVR
description: "Updates the [interactive voice response (IVR) system](https://support.zoom.us/hc/en-us/articles/360038601971) of the specified auto receptionist.\n\n**Prerequisites:**\n * A Business or Enterprise account \n* A Zoom Phone license\n\n**[Scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-overview/):** `phone:write:admin`\n\n**[Granular Scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-overview/):** `phone:update:auto_receptionist_ivr:admin`\n\n**[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `LIGHT`"
operationId: updateAutoReceptionistIVR
parameters:
- name: autoReceptionistId
in: path
description: The auto receptionist ID.
required: true
schema:
type: string
example: HpgmeAcmSVK-UY-0RxDcfg
requestBody:
content:
application/json:
schema:
type: object
properties:
audio_prompt_id:
type: string
description: The audio prompt's file ID.
example: j2IsurWLRR-yWcbNGqPnaA
caller_enters_no_action:
type: object
properties:
action:
type: integer
description: "The action when a caller enters no action after the prompt played. \n \n`-1` Disconnect the call \n \n`2` Forward to the user\n \n `4` Forward to the common area\n \n `5` Forward to Cisco/Polycom Room\n \n `6` Forward to the auto receptionist\n \n `7` Forward to the call queue\n \n `8` Forward to the shared line group\n\n `9` Forward to external contacts \n\n `10` Forward to a phone number\n\n `12` Play a message, then disconnect\n \n `15` Forward to the partner contact center\n\n `18` Forward to Microsoft Teams Resource Account. Required the license of Zoom Phone for Microsoft Teams. \n\n `19` Forward to the Zoom Contact Center voice flow. Required Zoom Contact Center license.\n\n `24` Forward to the ZVA(Zoom Virtual Agent) Receptionist\n\n `25` Forward to the Third-party agent\n"
example: 200
caller_no_input_timeout:
type: integer
description: The number of seconds to wait for the caller's input (DTMF keypad or voice) after the prompt plays before the IVR takes the no-action `action`. Applies only when `allow_callers_to_navigate_ivr.enable` is `true`; otherwise this value is ignored.
example: 3
default: 3
enum:
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
audio_prompt_repeat:
type: integer
description: The number of times to repeat the audio prompt.
example: 2
enum:
- 1
- 2
- 3
- 4
- 5
forward_to_extension_id:
type: string
description: The extension ID or partner contact center setting ID.
example: z97zV9NsSoa846i-ag3uEw
voicemail_greeting_id:
type: string
description: The voicemail greeting's file ID. Only takes effect when `action` is `12` (Play a message, then disconnect).
example: z97zV9NsSoa846i-ag3uEw
forward_to:
type: object
properties:
phone_number:
type: string
description: "The phone number or external number, in [E.164 format](https://en.wikipedia.org/wiki/E.164). \n\n* When `action` is `10` (Forward to Phone number/External number), this is the destination number. \n* When `action` is `19` (Forward to the Zoom Contact Center voice flow), this is the Zoom Contact Center number."
example: '+18889843519'
teams_app_id:
type: string
description: The ID of the Microsoft Teams Voice App to forward to. Required when `action` is `18` (Forward to Microsoft Teams Resource Account).
example: oB18huSERjqbzrsyL2bD5w
partner_contact_center_id:
type: string
description: The ID of the Partner Contact Center to forward to. Required when `action` is `15` (Forward to a Partner Contact Center).
example: 0za4SO7OQ5mxeHEP8nHvGg
zva_receptionist_id:
type: string
description: The ID of the ZVA(Zoom Virtual Agent) Receptionist to forward to. Required when `action` is `24` (Forward to the ZVA Receptionist).
example: 6uv8qMMDShm6OGgFTrQPbA
third_party_agent_id:
type: string
description: The ID of the Third-party agent to forward to. Required when `action` is `25` (Forward to the Third-party agent).
example: T0x6LuR4TBKWFY6_ulxaOQ
external_contact_id:
type: string
description: The ID of the external contact to forward to. Required when `action` is `9` (Forward to external contacts).
example: OJGi5xOFQPmrJbKg68-iWg
description: The forward target for the no-action `action`. The relevant ID field is required based on the selected `action`.
description: The action if caller enters no action after the prompt played.
holiday_id:
type: string
description: The auto receptionist holiday hours ID. If both `holiday_id` and `hours_type` are passed, `holiday_id` has the highest priority and `hours_type` is ignored.
example: YpLBylKbQKe1vEB1iSGatQ
break_id:
type: string
description: The auto receptionist break hours ID. Required when `hours_type` is `break_hours`. If `holiday_id` is also passed, `holiday_id` takes precedence
example: ULfeE4mgSImyelNmTekUfg
hours_type:
type: string
description: The type of hours.
example: closed_hours
default: business_hours
enum:
- business_hours
- closed_hours
- holiday_hours
- break_hours
key_action:
type: object
properties:
action:
type: integer
description: "The action after clicking the key. \n\nFor all keys (`0`-`9`, * or #)\n \n`100` Leave voicemail to the current extension \n \n`200` Leave voicemail to the user \n \n`300` Leave voicemail to the auto receptionist \n \n`400` Leave voicemail to the call queue \n \n`500` Leave voicemail to the shared line group \n \n`2` Forward to the user \n \n`3` Forward to Zoom Room \n \n`4` Forward to the common area \n \n`5` Forward to Cisco/Polycom Room \n \n`6` Forward to the auto receptionist \n \n`7` Forward to the call queue \n \n`8` Forward to the shared line group \n \n`9` Forward to external contacts \n \n`10` Forward to a phone number \n\n`12` Play a message, then disconnect\n \n`15` Forward to the partner contact center \n \n`16` Forward to the meeting service \n \n`17` Forward to the meeting service number \n\n`18` Forward to Microsoft Teams Resource Account. Required the license of Zoom Phone for Microsoft Teams. \n\n`19` Forward to the zoom contact center voice flow. Required Zoom Contact Center license.\n\n`24` Forward to the ZVA(Zoom Virtual Agent) Receptionist\n\n`25` Forward to the Third-party agent\n\n`27` Play a message, then repeat menu greeting\n\n`28` Play a message, then return to root menu\n\n`29` Play a message, then return to previous menu\n\n \n`-1` Disabled\n\nFor key `0`-`9` only:\n\n`26` Dial by Name\n**Note**: The value of `action = 26` (`Dial by Name`) is available only when **Dial by Name Directory** is enabled. For multi-site accounts, this is checked at the site level via [Get a phone site setting](https://developers.zoom.us/docs/api/phone/#tag/sites/get/phone/sites/{siteId}/settings/{settingType}) with `settingType=dial_by_name`; otherwise, it follows the account-level setting.\n\nFor key * or # only:\n \n`21` Repeat menu greeting \n \n`22` Return to the root menu \n \n`23` Return to the previous menu "
example: 200
key:
type: string
description: 'The key. It supports the following values: numeric(''0''-''9''), *, #.'
example: '0'
target:
type: object
properties:
extension_id:
type: string
description: The extension ID or partner contact center setting ID.
example: CQLPaj0oSCC0olJLmAfgwQ
phone_number:
type: string
description: "The phone number or external number, in [E.164 format](https://en.wikipedia.org/wiki/E.164). \n\n* When `action` is `10` (Forward to Phone number/External number), this is the destination number. \n* When `action` is `19` (Forward to the Zoom Contact Center voice flow), this is the Zoom Contact Center number."
example: '+12055437350'
teams_app_id:
type: string
description: The ID of the Microsoft Teams Voice App to forward to. Required when `action` is `18` (Forward to Microsoft Teams Resource Account).
example: oB18huSERjqbzrsyL2bD5w
partner_contact_center_id:
type: string
description: The ID of the Partner Contact Center to forward to. Required when `action` is `15` (Forward to a Partner Contact Center).
example: 0za4SO7OQ5mxeHEP8nH
# --- truncated at 32 KB (69 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zoom-phone/refs/heads/main/openapi/zoom-phone-ivr-api-openapi.yml