Zoom Phone Common Areas API

openapi: 3.2.0
info:
  title: Phone Common Areas 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: Common Areas
paths:
  /phone/common_areas:
    get:
      tags:
      - Common Areas
      summary: List common areas
      description: "Lists common areas under an account.\n\n**Prerequisites**\n\n* Pro or a higher account with Zoom Phone license \n* Account owner or admin permissions\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:common_area:admin`\n\n**[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `MEDIUM`"
      operationId: listCommonAreas
      parameters:
      - name: page_size
        in: query
        description: The total number of records returned from a single API call.
        required: false
        schema:
          maximum: 100
          type: integer
          example: 30
          default: 30
      - name: next_page_token
        in: query
        description: The next page token paginates through large result sets. A next page token returns 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_id
        in: query
        description: The unique identifier of the site. Use this query parameter if you have enabled multiple sites and would like to filter the response of this API call by a specific phone site. See Managing multiple sites or Adding a site for details.
        required: false
        schema:
          type: string
          example: 8f71O6rWT8KFUGQmJIFAdQ
      - name: calling_type
        in: query
        description: The Zoom Phone [calling plan number](https://developers.zoom.us/docs/api-reference/other-references/plans#zoom-phone-calling-plans).
        required: false
        schema:
          type: integer
          example: 100
      - name: common_area_device_type
        in: query
        description: 'The common area device type:

          - 1 Smartphone


          - 2 Desk Phone


          - 3 Zoom Phone Appliance'
        required: false
        schema:
          type: integer
          example: 1
          enum:
          - 1
          - 2
          - 3
      responses:
        '200':
          description: "**HTTP Status Code:** `200` **OK**  \n \n The list of common areas retrieved successfully."
          content:
            application/json:
              schema:
                type: object
                properties:
                  common_areas:
                    type: array
                    items:
                      type: object
                      properties:
                        calling_plans:
                          type: array
                          items:
                            type: object
                            properties:
                              name:
                                type: string
                                description: The name of the plan.
                                example: US/CA Metered Calling Plan
                              type:
                                type: integer
                                description: The Zoom Phone [calling plan number](https://marketplace.zoom.us/docs/api-reference/other-references/plans#zoom-phone-calling-plans).
                                example: 100
                              billing_account_id:
                                type: string
                                description: The ID of the billing account. It displays when the common area is in India.
                                example: 3WWAEiEjTj2IQuyDiKMd_A
                              billing_account_name:
                                type: string
                                description: The billing account name. It displays when the common area is in India.
                                example: Delhi billing
                              billing_subscription_id:
                                type: string
                                description: The billing subscription ID. It displays when the account supports billing multiple subscriptions.
                                example: FT-SUBREF-21168178
                              billing_subscription_name:
                                type: string
                                description: The billing subscription name. It displays when the account supports billing multiple subscriptions. It can be edited through the Billing page.
                                example: My Subscription
                        display_name:
                          type: string
                          description: The display name of the common area.
                          example: test_ca
                        extension_number:
                          type: integer
                          description: The extension number.
                          format: int64
                          example: 100012347
                        id:
                          type: string
                          description: The common area ID or common area extension ID.
                          example: JOZmuJ30Spyrw-v9vUzIrA
                        phone_numbers:
                          type: array
                          items:
                            type: object
                            properties:
                              display_name:
                                type: string
                                description: The phone number display name.
                                example: Phone number display name
                              id:
                                type: string
                                description: The phone number ID.
                                example: S5q4FDC3QsOCnO7LqHgqNw
                              number:
                                type: string
                                description: The phone number.
                                example: '+12058945543'
                              source:
                                type: string
                                description: The phone number source. The value can be either `internal` or `external`.
                                example: internal
                                enum:
                                - internal
                                - external
                        site:
                          type: object
                          properties:
                            id:
                              type: string
                              description: The unique identifier of the [site](https://support.zoom.us/hc/en-us/articles/360020809672-Managing-Multiple-Sites) that the common area desk phone is assigned.
                              example: 8f71O6rWT8KFUGQmJIFAdQ
                            name:
                              type: string
                              description: The name of the site.
                              example: Main Site
                        status:
                          type: string
                          description: The status of the common area.
                          example: offline
                          enum:
                          - online
                          - offline
                        desk_phones:
                          type: array
                          description: The common area's desk phones.
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                                description: The desk phone ID.
                                example: Aky1xpSLSc2PR0XOtj9XWQ
                              display_name:
                                type: string
                                description: The desk phone display name.
                                example: analog_ta
                              device_type:
                                type: string
                                description: The desk phone device type.
                                example: Poly obi504
                              status:
                                type: string
                                description: The desk phone status.
                                example: offline
                                enum:
                                - online
                                - offline
                  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: RaO87FrnwXvFQta5aV8sU5C3c9O8s9Nraq2
                  page_size:
                    type: integer
                    description: The total number of records returned from a single API call.
                    example: 30
        '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:common_area:admin
        openapi_authorization: []
      x-extensions:
        x-permissions: []
        x-macro-scopes:
        - phone:read:admin
        x-granular-scopes:
        - phone:read:common_area:admin
    post:
      tags:
      - Common Areas
      summary: Add a common area
      description: 'Adds an instance of a common area. You can configure devices shared by users and deployed in shared spaces.


        **Prerequisites**

        * Pro or a higher account with Zoom Phone license

        * Account owner or admin permissions




        **[Scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-overview/):** `phone:write:admin`


        **[Granular Scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-overview/):** `phone:write:common_area:admin`


        **[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `LIGHT`'
      operationId: addCommonArea
      requestBody:
        content:
          application/json:
            schema:
              required:
              - display_name
              type: object
              properties:
                calling_plans:
                  maxItems: 100
                  type: array
                  items:
                    type: object
                    properties:
                      type:
                        type: integer
                        description: The Zoom Phone [calling plan number](https://marketplace.zoom.us/docs/api-reference/other-references/plans#zoom-phone-calling-plans).
                        example: 100
                      billing_subscription_id:
                        type: string
                        description: The billing subscription ID. When there is more than one plan type A in this account, it cannot be empty.
                        example: FT-SUBREF-21168178
                country_iso_code:
                  type: string
                  description: The two-lettered country [code](https://marketplace.zoom.us/docs/api-reference/other-references/abbreviation-lists#countries).
                  example: US
                display_name:
                  type: string
                  description: The display name of the common area. Enter at least three characters.
                  example: test_ca
                extension_number:
                  type: integer
                  description: The extension number assigned to the common area. If the site code is enabled, provide the short extension number instead.
                  format: int64
                  example: 1001014
                site_id:
                  type: string
                  description: The unique identifier of the [site](https://support.zoom.us/hc/en-us/articles/360020809672). You can retrieve the identifier from the [List Phone Sites](https://marketplace.zoom.us/docs/api-reference/phone/methods#operation/listPhoneSites) API.
                  example: 8f71O6rWT8KFUGQmJIFAdQ
                timezone:
                  type: string
                  description: ' The [timezone ID](https://marketplace.zoom.us/docs/api-reference/other-references/abbreviation-lists) for the common area.'
                  example: America/Los_Angeles
                template_id:
                  type: string
                  description: "The unique identifier of the [Setting Template](https://support.zoom.com/hc/en/article?id=zm_kb&sysparm_article=KB0067442). \nYou can retrieve the identifier from the [List setting templates](https://developers.zoom.us/docs/api/rest/reference/phone/methods/#operation/listSettingTemplates) API.\nThe setting template must belong to the same site as the common area."
                  example: 2kFqiqSlS5udzWB5QqMiNg
      responses:
        '201':
          description: "**HTTP Status Code:** `201` **Created**  \n \n\nThe common area has been added successfully."
          content:
            application/json:
              schema:
                type: object
                properties:
                  display_name:
                    type: string
                    description: The display name of the common area.
                    example: test_ca
                  id:
                    type: string
                    description: The common area ID or common area extension ID.
                    example: JOZmuJ30Spyrw-v9vUzIrA
        '400':
          description: "**HTTP Status Code:** `400` <br>\n Bad Request  \n\n **Error Code:** `300` <br>\n Validation failed.<br>\n* Timezone not found in the system.\n* This country is not supported by Zoom Phone.\n* Site does not exist: {site_id}.<br>\n* The template type error or the template does not exist:{template_id}.<br>\n* The template's site is not the same as the common area's site.<br> <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:common_area:admin
        openapi_authorization: []
      x-extensions:
        x-permissions: []
        x-macro-scopes:
        - phone:write:admin
        x-granular-scopes:
        - phone:write:common_area:admin
  /phone/common_areas/activation_code:
    post:
      tags:
      - Common Areas
      summary: Generate activation codes for common areas
      description: 'Generates activation codes for common areas. You can add up to 50 common areas at a time.


        **Prerequisites**

        - Pro or a higher account with Zoom Phone license

        - Account owner or admin permissions


        **[Scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-overview/):** `phone:write:admin`


        **[Granular Scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-overview/):** `phone:write:common_area:admin`


        **[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `LIGHT`


        **Not supported in Gov cluster** '
      operationId: Generateactivationcodesforcommonareas
      requestBody:
        content:
          application/json:
            schema:
              required:
              - common_area_ids
              type: object
              properties:
                common_area_ids:
                  maxItems: 50
                  type: array
                  description: 'The `common_area_ids` is an array. Each element is the unique identifier of the common area. You can retrieve it from the [List Common Areas](https://developers.zoom.us/docs/api/phone/#tag/common-areas/GET/phone/common_areas/activation_codes) API.


                    '
                  items:
                    type: string
                    description: The common area ID or common area extension ID.
                    example: 5NmyHmVoRWWk4YT5ad6oxg
      responses:
        '201':
          description: 'HTTP Status Code: 201 Generate Activation Codes successfully.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  common_areas_activation_codes:
                    maxItems: 50
                    type: array
                    description: The activation code information of the common areas.
                    items:
                      type: object
                      properties:
                        common_area_id:
                          type: string
                          description: The common area ID or common area extension ID.
                          example: JOZmuJ30Spyrw-v9vUzIrA
                        display_name:
                          type: string
                          description: The display name of the common area.
                          example: test_ca
                        extension_number:
                          type: integer
                          description: The extension number.
                          example: 100012347
                        activation_code:
                          type: string
                          description: The activation code.
                          example: 5678-2345-1234-1234
                        activation_code_expiration:
                          type: string
                          description: 'The time when the activation code expires (format: ''yyyy-MM-ddThh:dd:ssZ'').'
                          example: '2021-10-08T16:12:04Z'
        '400':
          description: "**HTTP Status Code:** `400` <br>\n Bad Request  \n\n **Error Code:** `400` <br>\n Common area size must be less than 50. <br>\n**Error Code:** `404` <br>\n Common area does not exist: {commonAreaId}. <br>\n**Error Code:** `400` <br>\n Common area smartphones feature is disabled. <br>\n"
        '403':
          description: "**HTTP Status Code:** `403` <br>\n Forbidden  \n\n **Error Code:** `403` <br>\n You do not have permission. <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:common_area:admin
        openapi_authorization: []
      x-extensions:
        x-permissions: []
        x-macro-scopes:
        - phone:write:admin
        x-granular-scopes:
        - phone:write:common_area:admin
  /phone/common_areas/activation_codes:
    get:
      tags:
      - Common Areas
      summary: List activation codes
      description: "Returns a list of activation code information of the common areas under an account.\n\n**Prerequisites**\n* Pro or a higher account with Zoom Phone license \n* Account owner or admin permissions\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_common_area_activation_codes:admin`\n\n**[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `MEDIUM`\n\n**Not supported in Gov cluster** "
      operationId: listActivationCodes
      parameters:
      - name: page_size
        in: query
        description: The total number of records returned from a single API call.
        required: false
        schema:
          maximum: 100
          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 returns 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
      responses:
        '200':
          description: "**HTTP Status Code:** `200` **OK**  \n \n The list of activation codes of the common areas retrieved successfully."
          content:
            application/json:
              schema:
                type: object
                properties:
                  common_areas_activation_codes:
                    type: array
                    description: The activation code information of the common areas.
                    items:
                      type: object
                      properties:
                        common_area_id:
                          type: string
                          description: The common area ID or common area extension ID.
                          example: JOZmuJ30Spyrw-v9vUzIrA
                        display_name:
                          type: string
                          description: The display name of the common area.
                          example: test_ca
                        extension_number:
                          type: integer
                          description: The extension number.
                          format: int64
                          example: 100012347
                        activation_code:
                          type: string
                          description: The activation code.
                          example: 5678-2345-1234-1234
                        activation_code_expiration:
                          type: string
                          description: 'The time when the activation code expires (format: ''yyyy-MM-ddThh:dd:ssZ'').'
                          example: '2021-10-08T16:12:04Z'
                        status:
                          type: string
                          description: "The values of this field can be `used` or `not_used`. \n \n used: The common area has been logged in to a smartphone through an activation code.  \n \n not_used: The common area is never logged in to a smartphone through an activation code."
                          example: used
                          enum:
                          - used
                          - not_used
                        site:
                          type: object
                          properties:
                            site_id:
                              type: string
                              description: The unique identifier of the [site](https://support.zoom.us/hc/en-us/articles/360020809672-Managing-Multiple-Sites) that the common area is assigned.
                              example: 8f71O6rWT8KFUGQmJIFAdQ
                            name:
                              type: string
                              description: The name of the site.
                              example: Main Site
                  next_page_token:
                    type: string
                    description: The next page token paginates through a large set of results. A next page token returns whenever the set of available results exceeds the current page size. The expiration period for this token is 15 minutes.
                    example: RaO87FrnwXvFQta5aV8sU5C3c9O8s9Nraq2
                  page_size:
                    type: integer
                    description: The total number of records returned from a single API call.
                    example: 30
        '400':
          description: "**HTTP Status Code:** `400` <br>\n Bad Request  \n\n **Error Code:** `400` <br>\n The next page token is invalid or expired. <br>\n**Error Code:** `400` <br>\n The account_id is invalid. <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:list_common_area_activation_codes:admin
        openapi_authorization: []
      x-extensions:
        x-permissions: []
        x-macro-scopes:
        - phone:read:admin
        x-granular-scopes:
        - phone:read:list_common_area_activation_codes:admin
  /phone/common_areas/template_id/{templateId}:
    post:
      tags:
      - Common Areas
      summary: Apply template to common areas
      description: 'Applies a template to common areas.  You can add up to 50 common areas at a time.


        **Prerequisites**

        * Pro or a higher account with Zoom Phone license

        * Account owner or admin permissions



        **[Scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-overview/):** `phone:write:admin`


        **[Granular Scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-overview/):** `phone:write:apply_template_to_common_areas:admin`


        **[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `LIGHT`'
      operationId: ApplyTemplatetoCommonAreas
      parameters:
      - name: templateId
        in: path
        description: "The template ID is the unique identifier of the [Setting Template](https://support.zoom.com/hc/en/article?id=zm_kb&sysparm_article=KB0067442). \nYou can retrieve the identifier from the [List setting templates](https://developers.zoom.us/docs/api/rest/reference/phone/methods/#operation/listSettingTemplates) API.\nIf the account enabled [multiple sites](https://support.zoom.com/hc/en/article?id=zm_kb&sysparm_article=KB0069716#h_05c88e35-1593-491f-b1a8-b7139a75dc15), the setting template must belong to the same site as the common areas."
        required: true
        schema:
          type: string
          example: 2kFqiqSlS5udzWB5QqMiNg
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                common_area_ids:
                  maxItems: 50
                  type: array
                  description: The `common_area_ids` is an array. Each element is the unique identifier of the [Common Area](https://marketplace.zoom.us/docs/api-reference/phone/methods/#operation/listCommonAreas). It can be retrieved from the List Common Areas API.
                  items:
                    type: string
                    description: The common area ID or common area extension ID.
                    example: 5NmyHmVoRWWk4YT5ad6oxg
      responses:
        '201':
          description: '**HTTP Status Code:** `201`   Template applied successfully.'
        '400':
          description: "**HTTP Status Code:** `400` <br>\n Bad Request  \n\n **Error Code:** `300` <br>\n The template's site is not the same as the common area's site. <br>\n**Error Code:** `400` <br>\n Common area size must be less than 50. <br> \nYou need to have administrative privileges to edit this site. <br>\n**Error Code:** `404` <br>\n Common area does not exist: {commonAreaId}. <br>\n"
        '404':
          description: "**HTTP Status Code:** `404` <br>\n Not Found  The template type error or the template does not exist:{templateId}. \n\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:apply_template_to_common_areas:admin
        openapi_authorization: []
      x-extensions:
        x-permissions: []
        x-macro-scopes:
        - phone:write:admin
        x-granular-scopes:
        - phone:write:apply_template_to_common_areas:admin
  /phone/common_areas/{commonAreaId}:
    get:
      tags:
      - Common Areas
      summary: Get common area details
      description: "Returns detailed information on the common area.\n\n**Prerequisites**  \n \n* Pro or a higher account with Zoom Phone license\n* Account owner or admin permissions\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:common_area:admin`\n\n**[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `LIGHT`"
      operationId: getACommonArea
      parameters:
      - name: commonAreaId
        in: path
        description: The common area ID or common area extension ID.
        required: true
        schema:
          type: string
          example: 5NmyHmVoRWWk4YT5ad6oxg
      responses:
        '200':
          description: "**HTTP Status Code:** `200` **OK**  \n \nCommon area details returned successfully."
          content:
            application/json:
              schema:
                type: object
                properties:
                  area_code:
                    type: string
                    description: The area code of the common area.
                    example: '408'
                  calling_plans:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          description: The calling plan name.
                          example: US/CA Metered Calling Plan
                        type:
                          type: integer
                          description: The calling plan type.
                          example: 100
                        billing_account_id:
                          type: string
                          description: The billing account ID. It displays when the common area is in India.
                          example: 3WWAEiEjTj2IQuyDiKMd_A
                        billing_account_name:
                          type: string
                          description: The billing account name. It displays when the common area is in India.
                          example: Delhi billing
                        billing_subscription_id:
                          type: string
                          description: The billing subscription ID. It displays when the account supports billing multiple subscriptions.
                          example: FT-SUBREF-21168178
                        billing_subscription_name:
                          type: string
                          description: The billing subscription name. It displays when the account supports billing multiple subscriptions. It can be edited via the Billing page.
                          example: My Subscription
                  cost_center:
                    type: string
                    description: The cost center the common area belongs to.
                    example: pbx_cost_center
                  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
                      country_code:
                        type: string
                        description: The country calling code.
                        example: '1'
                      name:
                        type: string
                        d

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