Zoom Phone Sites API

openapi: 3.2.0
info:
  title: Phone Sites 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: Sites
paths:
  /phone/sites:
    get:
      tags:
      - Sites
      summary: List phone sites
      description: "Sites allow you to organize Zoom Phone users in your organization. Use this API to list all the [sites](https://support.zoom.us/hc/en-us/articles/360020809672) that have been created for an account.  \n \n**Prerequisites:**  \n \n* Multiple Sites must be [enabled](https://support.zoom.us/hc/en-us/articles/360020809672-Managing-Multiple-Sites#h_05c88e35-1593-491f-b1a8-b7139a75dc15).\n* Pro or a higher account with Zoom Phone enabled.\n\n\n\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:list_sites:admin`\n\n**[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `MEDIUM`"
      operationId: listPhoneSites
      parameters:
      - name: page_size
        in: query
        description: The number of records returned within a single API call.
        required: false
        schema:
          maximum: 300
          type: integer
          example: 30
          default: 30
      - name: next_page_token
        in: query
        description: The next page token paginates through a large set of results. A next page token is returned whenever the set of available results exceeds the current page size. The expiration period for this token is 15 minutes.
        required: false
        schema:
          type: string
          example: BJLYC6PABbAHdjwSkGVQeeR6B1juwHqj3G2
      - name: site_name
        in: query
        description: The name of the site you want to search.
        required: false
        schema:
          type: string
          example: Main Site
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  next_page_token:
                    type: string
                    description: The next page token paginates through a large set of results. A next page token is returned whenever the set of available results exceeds the current page size. The expiration period for this token is 15 minutes.
                    example: nav48KOj42vYPSG4f0cCdT575bZ980did22
                  page_size:
                    type: integer
                    description: The number of records returned within a single API call.
                    example: 10
                  sites:
                    type: array
                    description: List of site(s).
                    items:
                      type: object
                      properties:
                        country:
                          type: object
                          properties:
                            code:
                              type: string
                              description: The two lettered country [code](https://marketplace.zoom.us/docs/api-reference/other-references/abbreviation-lists#countries).
                              example: US
                            name:
                              type: string
                              description: The name of the country.
                              example: United States
                          description: The country of the site.
                        id:
                          type: string
                          description: The site ID is the unique identifier of the site.
                          example: SQv52YtkRLC2dwrDdYtGsA
                        main_auto_receptionist:
                          type: object
                          properties:
                            extension_id:
                              type: string
                              description: The extension ID
                              example: pl1XprjhTQK1CCMVKTqCFA
                            extension_number:
                              type: integer
                              description: The extension number
                              format: int64
                              example: 12345
                            id:
                              type: string
                              description: The identifier of the [auto receptionist](https://support.zoom.us/hc/en-us/articles/360021121312-Managing-Auto-Receptionists-and-Interactive-Voice-Response-IVR-).
                              example: Kbdc9lv_SBCuPMjj_lhxVA
                            name:
                              type: string
                              description: The name of the auto receptionist.
                              example: ApiTA_R_2020_07_12_00_41_57_145
                          description: The auto receptionist for each site.
                        name:
                          type: string
                          description: The name of the site.
                          example: ApiTA_Site_2020_07_12_00_41_57_141
                        site_code:
                          type: integer
                          description: The site code
                          example: 1
                  total_records:
                    type: integer
                    description: The total number of records returned.
                    example: 20
        '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:list_sites:admin
        openapi_authorization: []
      x-extensions:
        x-permissions: []
        x-macro-scopes:
        - phone:read:admin
        x-granular-scopes:
        - phone:read:list_sites:admin
    post:
      tags:
      - Sites
      summary: Create a phone site
      description: "Creates a [site](https://support.zoom.us/hc/en-us/articles/360020809672) that allows you to organize the Zoom Phone users in your organization.\n\n**Prerequisites:**\n* Multiple sites must be [enabled](https://support.zoom.us/hc/en-us/articles/360020809672-Managing-Multiple-Sites#h_05c88e35-1593-491f-b1a8-b7139a75dc15). \n* Pro or a higher account with Zoom Phone enabled.\n\n\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:write:site:admin`\n\n**[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `LIGHT`"
      operationId: createPhoneSite
      requestBody:
        content:
          application/json:
            schema:
              required:
              - auto_receptionist_name
              - default_emergency_address
              - name
              type: object
              properties:
                auto_receptionist_name:
                  type: string
                  description: The display name of the [auto-receptionist](https://support.zoom.us/hc/en-us/articles/360021121312-Managing-Auto-Receptionists-and-Integrated-Voice-Response-IVR-) for the site.
                  example: ApiTA_R_2020_07_12_00_41_57_145
                source_auto_receptionist_id:
                  type: string
                  description: The ID of the [auto-receptionist](https://support.zoom.us/hc/en-us/articles/360021121312-Managing-Auto-Receptionists-and-Integrated-Voice-Response-IVR-) that you can copy.
                  example: 0m0dGevHR2ulyMgxFLeVEA
                default_emergency_address:
                  required:
                  - address_line1
                  - city
                  - country
                  - state_code
                  - zip
                  type: object
                  properties:
                    address_line1:
                      type: string
                      description: The address Line 1 of the [emergency address](https://support.zoom.us/hc/en-us/articles/360021062871-Setting-an-Emergency-Address) that contains the house number and street name.
                      example: 55 Almaden Boulevard
                    address_line2:
                      type: string
                      description: The address Line 2 of the [emergency address](https://support.zoom.us/hc/en-us/articles/360021062871-Setting-an-Emergency-Address) that contains the building number, floor number, unit, and others.
                      example: 8 Floor
                    city:
                      type: string
                      description: The city of the [emergency address](https://support.zoom.us/hc/en-us/articles/360021062871-Setting-an-Emergency-Address).
                      example: SAN JOSE
                    country:
                      maxLength: 2
                      minLength: 2
                      type: string
                      description: The two-lettered country code (Alpha-2 code in ISO-3166 format) of the site's [emergency address](https://support.zoom.us/hc/en-us/articles/360021062871-Setting-an-Emergency-Address).
                      example: US
                    state_code:
                      type: string
                      description: The state code of the [emergency address](https://support.zoom.us/hc/en-us/articles/360021062871-Setting-an-Emergency-Address).
                      example: CA
                    zip:
                      type: string
                      description: The zip code of the [emergency address](https://support.zoom.us/hc/en-us/articles/360021062871-Setting-an-Emergency-Address).
                      example: '95113'
                  description: The default emergency address. If the address provided is not an exact match, it uses the system generated corrected address.
                name:
                  maxLength: 255
                  minLength: 1
                  type: string
                  description: The name of the site.
                  example: Main site
                short_extension:
                  type: object
                  properties:
                    length:
                      type: integer
                      description: 'The length of short extension numbers for the site.


                        Since there is a default 6-digit limit on extensions, the short extension can be two to five digits. The length of site code added to the length of short extension cannot exceed a value of `6` For example, the length of `site_code`+ length of `short_extension` should always be less than or equal to 6.'
                      example: 4
                      default: 3
                  description: The short extension of the phone site.
                site_code:
                  type: integer
                  description: 'The identifier for a site. This field is required when the site code is enabled.


                    '
                  example: 2
                sip_zone:
                  type: object
                  properties:
                    id:
                      type: string
                      description: The SIP zone ID.
                      example: 2J9UXzGuTaqCdZ8sw_0jBw
                  description: If the account enabled the `Display Custom SIP Zone Options on Web Portal` feature, then selecting a SIP zone nearest to your site might help reduce latency and improve call quality.
                force_off_net:
                  type: object
                  properties:
                    enable:
                      type: boolean
                      description: 'By enabling Force Off-Net, calls from users or extensions between sites route through the PSTN network. Users in this site are only allowed to be part of the advanced functionality (eg. Auto Receptionists, Call Queues) configured in this site. '
                      example: true
                    allow_extension_only_users_call_users_outside_site:
                      type: boolean
                      description: This setting allows extension only users to call to users outside the site.
                      example: true
                  description: 'It requires the account to enable the `Force Calls out to the PSTN network` feature. '
                india_state_code:
                  type: string
                  description: The India site’s state code. This field only applies to India based accounts.
                  example: CG
                india_city:
                  type: string
                  description: The India site’s city. This field only applies to India based accounts.
                  example: Bemetara
                india_sdca_npa:
                  type: string
                  description: The India site’s Short Distance Calling Area (sdca) Numbering Plan Area (npa). This field is linked to the “state_code“ field. This field only applies to India based accounts.
                  example: '7700'
                india_entity_name:
                  type: string
                  description: When select the Indian sip zone, then need to set the entity name. This field only applies to India based accounts.
                  example: india-test-entity
      responses:
        '201':
          description: '**HTTP Status Code:** `201` **Created**   Site created successfully.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: ' The site ID is the unique identifier of a site.'
                    example: SQv52YtkRLC2dwrDdYtGsA
                  name:
                    type: string
                    description: ' The name of the site.'
                    example: ApiTA_Site_2020_07_12_00_41_57_141
        '400':
          description: "**HTTP Status Code:** `400` <br>\n Bad Request  \n\n **Error Code:** `400` <br>\n Invalid site code length.<br>Country information is invalid.<br>This address could not be validated or geocoded. <br>\n**Error Code:** `400` <br>\n For India sites, state and city should not be empty. <br>\n**Error Code:** `400` <br>\n Short Distance Calling Area is invalid. <br>\n**Error Code:** `400` <br>\n India Entity Name is required. <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:write:admin
        - phone:write:site:admin
        openapi_authorization: []
      x-extensions:
        x-permissions: []
        x-macro-scopes:
        - phone:write:admin
        x-granular-scopes:
        - phone:write:site:admin
  /phone/sites/{siteId}:
    get:
      tags:
      - Sites
      summary: Get phone site details
      description: "Returns information on a specific [site](https://support.zoom.us/hc/en-us/articles/360020809672). \n\nSites allow you to organize Zoom Phone users in your organization. \n\n**Prerequisites** \n* Account must have a Pro or a higher plan with Zoom Phone license.\n* Multiple sites must be [enabled](https://support.zoom.us/hc/en-us/articles/360020809672-Managing-Multiple-Sites#h_05c88e35-1593-491f-b1a8-b7139a75dc15).\n\n\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:site:admin`\n\n**[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `LIGHT`"
      operationId: getASite
      parameters:
      - name: siteId
        in: path
        description: The unique identifier of the site.
        required: true
        schema:
          type: string
          example: SQv52YtkRLC2dwrDdYtGsA
      responses:
        '200':
          description: "**HTTP Status Code:** `200`  \n \nSite information retrieved successfully."
          content:
            application/json:
              schema:
                type: object
                properties:
                  country:
                    type: object
                    properties:
                      code:
                        type: string
                        description: The two lettered country [code](https://marketplace.zoom.us/docs/api-reference/other-references/abbreviation-lists#countries).
                        example: US
                      name:
                        type: string
                        description: The name of the country.
                        example: United States
                    description: The country of the site.
                  id:
                    type: string
                    description: The site ID is the unique identifier of the site.
                    example: SQv52YtkRLC2dwrDdYtGsA
                  main_auto_receptionist:
                    type: object
                    properties:
                      extension_id:
                        type: string
                        description: The extension ID.
                        example: pl1XprjhTQK1CCMVKTqCFA
                      extension_number:
                        type: integer
                        description: The extension number.
                        format: int64
                        example: 12345
                      id:
                        type: string
                        description: The unique identifier of the auto receptionist.
                        example: Kbdc9lv_SBCuPMjj_lhxVA
                      name:
                        type: string
                        description: The name of the auto receptionist.
                        example: ApiTA_R_2020_07_12_00_41_57_145
                    description: ' The [main auto receptionist](https://support.zoom.us/hc/en-us/articles/360021121312#h_bc7ff1d5-0e6c-40cd-b889-62010cb98c57) for each site.'
                  name:
                    type: string
                    description: The name of the site.
                    example: ApiTA_Site_2020_07_12_00_41_57_141
                  short_extension:
                    type: object
                    properties:
                      length:
                        type: integer
                        description: The length of the short extension number for the site.
                        example: 3
                        default: 3
                    description: The short extension of the phone site.
                  site_code:
                    type: integer
                    description: The [site code](https://support.zoom.us/hc/en-us/articles/360020809672-Managing-Multiple-Sites#h_79ca9c8f-c97b-4486-aa59-d0d9d31a525b).
                    example: 321
                  policy:
                    type: object
                    properties:
                      select_outbound_caller_id:
                        type: object
                        properties:
                          enable:
                            type: boolean
                            description: Whether to allow the current extension to change the outbound caller ID when placing calls.
                            example: true
                          locked:
                            type: boolean
                            description: Whether the senior administrator allows users to modify the current settings.
                            example: true
                          locked_by:
                            type: string
                            description: Which level of administrator prohibits the modification of the current settings.
                            example: site
                            enum:
                            - invalid
                            - account
                            - site
                          modified:
                            type: boolean
                            description: Whether the current settings have been modified. If modified, they can be reset. The settings display when using the new policy framework.
                            example: true
                          allow_hide_outbound_caller_id:
                            type: boolean
                            description: Whether to allow the current extension to hide outbound caller ID.
                            example: true
                        description: ' Whether to allow the current extension to change the outbound caller ID when placing calls.'
                      personal_audio_library:
                        type: object
                        properties:
                          enable:
                            type: boolean
                            description: This field allows users to access, share, download, or delete voicemail or videomail.
                            example: true
                          locked:
                            type: boolean
                            description: Whether the senior administrator allows users to modify the current settings.
                            example: true
                          locked_by:
                            type: string
                            description: Which level of administrator prohibits the modification of the current settings.
                            example: site
                            enum:
                            - invalid
                            - account
                            - site
                          modified:
                            type: boolean
                            description: Whether the current settings have been modified. If modified, they can be reset. The settings display when using the new policy framework.
                            example: true
                          allow_music_on_hold_customization:
                            type: boolean
                            description: Whether to allow music on hold customization.
                            example: true
                          allow_voicemail_and_message_greeting_customization:
                            type: boolean
                            description: Whether to allow voicemail and message greeting customization.
                            example: true
                        description: Allows users to change their own Audio Library.
                      voicemail:
                        type: object
                        properties:
                          allow_delete:
                            type: boolean
                            description: This setting allows users to delete their own voicemail. It displays only when using the new policy framework.
                            example: true
                          allow_download:
                            type: boolean
                            description: This setting allows users to download their own voicemail. It displays only when using the new policy framework.
                            example: false
                          allow_videomail:
                            type: boolean
                            description: This setting allows users to access, share, download or delete video mail
                            example: true
                          enable:
                            type: boolean
                            description: This setting allows users to access, receive, or share voicemail and video mail.
                            example: true
                          locked:
                            type: boolean
                            description: Whether the senior administrator allows users to modify the current settings.
                            example: true
                          locked_by:
                            type: string
                            description: Which level of administrator can prohibit users to modify the current settings.
                            example: site
                            enum:
                            - invalid
                            - account
                            - site
                          modified:
                            type: boolean
                            description: Whether the current settings have been modified. If modified, they can be reset. The settings display when using the new policy framework.
                            example: true
                        description: Allows users to access, share, download, and to delete voicemail and videomail
                      voicemail_transcription:
                        type: object
                        properties:
                          enable:
                            type: boolean
                            description: Whether to allow users to access transcriptions of voicemails from the Zoom client, the Zoom web portal, and email notifications.
                            example: true
                          locked:
                            type: boolean
                            description: Whether the senior administrator allows users to modify the current settings.
                            example: true
                          locked_by:
                            type: string
                            description: Which level of administrator prohibits the modification of the current settings.
                            example: site
                            enum:
                            - invalid
                            - account
                            - site
                          modified:
                            type: boolean
                            description: Whether the current settings have been modified. If modified, they can be reset. The settings display when using the new policy framework.
                            example: true
                        description: When this setting is enabled, voicemail and videomail transcriptions will be created and remain accessible even if the setting is later disabled. If the setting is disabled, new voicemail and videomail transcriptions will not be generated.
                      voicemail_notification_by_email:
                        type: object
                        properties:
                          include_voicemail_file:
                            type: boolean
                            description: Whether to include the voicemail file.
                            example: true
                          include_voicemail_transcription:
                            type: boolean
                            description: Whether to include the voicemail transcription.
                            example: false
                          forward_voicemail_to_email:
                            type: boolean
                            description: Whether to forward the voicemail to email.
                            example: true
                          enable:
                            type: boolean
                            example: true
                          locked:
                            type: boolean
                            description: Whether the senior administrator allows users to modify the current settings.
                            example: true
                          locked_by:
                            type: string
                            description: Which level of administrator prohibits the modification of the current settings.
                            example: site
                            enum:
                            - invalid
                            - account
                            - site
                          modified:
                            type: boolean
                            description: Whether the current settings have been modified. If modified, they can be reset. The settings display when using the new policy framework.
                            example: true
                        description: Once enabled, users receive email notifications when there is a new voicemail from users, call queues, auto receptionists, or shared line groups. Users who disabled the shared voicemail notification by email policy receive notifications. They display when the voicemail policy uses the new policy framework.
                      shared_voicemail_notification_by_email:
                        type: object
                        properties:
                          enable:
                            type: boolean
                            example: true
                          locked:
                            type: boolean
                            description: Whether the senior administrator allows users to modify the current settings.
                            example: true
                          locked_by:
                            type: string
                            description: Which level of administrator can prohibit users to modify the current settings.
                            example: site
                            enum:
                            - invalid
                            - account
                            - site
                          modified:
                            type: boolean
                            description: Whether the current settings have been modified. If modified, they can be reset and display when using the new policy framework.
                            example: true
                        description: Once enabled, users will receive email notification when there is a new shared voicemail/videomail. If the extension that shares the voicemail or videomail has disabled the voicemail or videomail notification by email policy, users will not receive notifications. They only display when the voicemail policy uses the new policy framework.
                      international_calling:
                        type: object
                        properties:
                          enable:
                            type: boolean
                            example: true
                          locked:
                            type: boolean
                            description: Whether the senior administrator allows users to modify the current settings.
                            example: true
                          locked_by:
                            type: string
                            description: Which level of administrator can prohibit users to modify the current settings.
                            example: site
                            enum:
                            - invalid
                            - account
                            - site
                          modified:
                            type: boolean
                            description: Whether the current settings have been modified. If modified, they can be reset. The settings display when using the new policy framework.
                            example: true
                        description: Whether to allow extensions to place international calls outside of the calling plan.
                      zoom_phone_on_mobile:
                        type: object
                        properties:
                          allow_calling_clients:
                            type: array
                            description: The clients in this list are allowed to make and receive calls.
                            items:
                              type: string
                              description: "The acceptable valu

# --- truncated at 32 KB (381 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zoom-phone/refs/heads/main/openapi/zoom-phone-sites-api-openapi.yml