Zoom Phone Phone Devices API

openapi: 3.2.0
info:
  title: Phone Devices 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: Phone Devices
paths:
  /phone/devices:
    get:
      tags:
      - Phone Devices
      summary: List devices
      description: "Lists all the [desk phone devices](https://support.zoom.us/hc/en-us/articles/360021119092) that are configured with Zoom Phone on an account.\n\n**Prerequisites:**  \n \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_devices:admin`\n\n**[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `MEDIUM`"
      operationId: listPhoneDevices
      parameters:
      - name: type
        in: query
        description: 'The device status: `assigned` or `unassigned` to list device status in Zoom account.'
        required: true
        schema:
          type: string
          example: assigned
          enum:
          - assigned
          - unassigned
      - name: assignee_type
        in: query
        description: The type of the assignee. It's available if `type = assigned`. It's unavailable if the account has not enabled the common area feature. It also returns devices of the specified `assignee_type`. If unspecified, it returns all assigned devices.
        required: false
        schema:
          type: string
          example: user
          enum:
          - user
          - commonArea
      - name: device_source
        in: query
        description: The device source. `hotDesking` is only available when `type = assigned`.
        required: false
        schema:
          type: string
          example: haas
          enum:
          - haas
          - hotDesking
      - name: location_status
        in: query
        description: The status of device location. It's available if `type = assigned`.
        required: false
        schema:
          type: string
          example: unknownAddress
          enum:
          - unknownAddress
      - name: site_id
        in: query
        description: The site of the assignee.
        required: false
        schema:
          type: string
          example: lA68sMSVQ6GAUcGg_GH0nQ
      - name: device_type
        in: query
        description: The manufacturer name or device type.
        required: false
        schema:
          type: string
          example: audioCodes
          enum:
          - algo
          - audioCodes
          - cisco
          - cyberData
          - grandstream
          - poly
          - yealink
          - other
      - name: keyword
        in: query
        description: The user, extension, MAC address, or IP address to filter the results.
        required: false
        schema:
          type: string
          example: 80-5e-c0-ce-ef-2f
      - 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
      - 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
      responses:
        '200':
          description: "**HTTP Status Code:** `200`  \n \nDevices listed successfully. "
          content:
            application/json:
              schema:
                type: object
                properties:
                  devices:
                    type: array
                    items:
                      type: object
                      properties:
                        assignee:
                          type: object
                          properties:
                            extension_number:
                              type: integer
                              description: The extension number of the Zoom Phone the `user` or `commonArea`uses.
                              format: int64
                              example: 123
                            id:
                              type: string
                              description: The ID of the user or commonArea to whom the device has been assigned.
                              example: -tDdYIstSumpA0L13GztIQ
                            name:
                              type: string
                              description: Name.
                              example: Pooja
                            extension_type:
                              type: string
                              description: The type of the assignee. It's available only if the device is assigned.
                              example: user
                              enum:
                              - user
                              - commonArea
                        assignees:
                          type: array
                          items:
                            type: object
                            properties:
                              extension_number:
                                type: integer
                                description: The extension number of the Zoom Phone the `user` or `commonArea`uses.
                                format: int64
                                example: 123
                              id:
                                type: string
                                description: The ID of the user or commonArea to whom the device has been assigned.
                                example: -tDdYIstSumpA0L13GztIQ
                              name:
                                type: string
                                description: Name.
                                example: Pooja
                              extension_type:
                                type: string
                                description: The type of the assignee. It's available only if the device is assigned.
                                example: user
                                enum:
                                - user
                                - commonArea
                              extension_id:
                                type: string
                                description: The extension ID of the `user` or `common area`.
                                example: MjGXQfCxShapaxJDka7
                        device_type:
                          type: string
                          description: This field provides the manufacturer name and the model name.
                          example: AudioCodes405
                        display_name:
                          type: string
                          description: Display name of the device.
                          example: Pooja's Phone
                        id:
                          type: string
                          description: The device ID.
                          example: -tDdYIstSumpA0L13GztIQ
                        mac_address:
                          type: string
                          description: The MAC address or serial number of the device.
                          example: 203a07240534
                        site:
                          type: object
                          properties:
                            id:
                              type: string
                              description: The [site](https://support.zoom.us/hc/en-us/articles/360020809672) of the phone user.
                              example: NjHmTu16Qfe8yOiNJuekXA
                            name:
                              type: string
                              description: The name of the [site](https://support.zoom.us/hc/en-us/articles/360020809672).
                              example: HQ site
                        status:
                          type: string
                          description: The status of the device. The value is either `online` or `offline`.
                          example: online
                          enum:
                          - online
                          - offline
                        provision_template_id:
                          type: string
                          description: The provision template ID. It's supported only by some devices. An empty string represents 'No value set'
                          example: Ke5Ghevvoo001hr
                        description:
                          type: string
                          description: The description of the device.
                          example: This device is used for testing.
                        firmware_version:
                          type: string
                          description: The firmware version of the device.
                          example: 108.86.3.9
                        private_ip:
                          type: string
                          description: The private IP of the registered device.
                          example: 192.168.10.13
                        public_ip:
                          type: string
                          description: The public IP of the registered device.
                          example: 220.143.231.126
                        policy:
                          type: object
                          properties:
                            call_control:
                              type: object
                              properties:
                                status:
                                  type: string
                                  description: "This field enables the call control feature to the current device. It configures the desk phone devices to enable call control, which allows users to perform desk phone's call control actions from the Zoom desktop client, including making and accepting calls. \nOptions include: \n* `unsupported` \n* `on` \n* `off`"
                                  example: 'off'
                                  enum:
                                  - unsupported
                                  - 'on'
                                  - 'off'
                            hot_desking:
                              type: object
                              properties:
                                status:
                                  type: string
                                  description: "This field enables the hot desking feature to the current device. It lets the guest user sign in to the desk phone. You can't use the desk phone until the guest user signs out. \nOptions include:\n* `unsupported` \n* `on` \n* `off`"
                                  example: 'off'
                                  enum:
                                  - unsupported
                                  - 'on'
                                  - 'off'
                          description: The device policy.
                  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: uBTK3NzNksdkuCUAQaFVFd86kyOr59zg4U2
                  page_size:
                    type: integer
                    description: The number of records returned with a single API call.
                    example: 30
                  total_records:
                    type: integer
                    description: The total number of records found for the query across all pages.
                    example: 1
        '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_devices:admin
        openapi_authorization: []
      x-extensions:
        x-permissions: []
        x-macro-scopes:
        - phone:read:admin
        x-granular-scopes:
        - phone:read:list_devices:admin
    post:
      tags:
      - Phone Devices
      summary: Add a device
      description: "[Adds an unassigned desk phone or an assigned (to a user or a common area) desk phone.](https://support.zoom.com/hc/en/article?id=zm_kb&sysparm_article=KB0061431#h_5ca07504-68a8-4c3d-ad0e-c1d3594436da)\n\n**Prerequisites:**  \n \n* Pro or a higher account with Zoom Phone license\n* Account owner or admin permissions\n* [Supported device](https://support.zoom.us/hc/en-us/articles/360001299063-Zoom-Voice-Supported-Devices)  \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:device:admin`\n\n**[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `LIGHT`"
      operationId: addPhoneDevice
      requestBody:
        content:
          application/json:
            schema:
              required:
              - display_name
              - mac_address
              - type
              type: object
              properties:
                assigned_to:
                  type: string
                  description: The user ID or email address of the user to whom this device will be assigned.
                  example: -tDdYIstSumpA0L13GztIQ
                assignee_extension_ids:
                  maxItems: 10
                  type: array
                  description: An array of extension IDs for users or common areas.
                  items:
                    type: string
                    example: dsH7FaYRHy9gV4Qb8ecku
                display_name:
                  maxLength: 255
                  type: string
                  description: The display name of the desk phone.
                  example: Desk Phone
                mac_address:
                  pattern: ^([0-9A-Fa-f]{2}[:-]?){5}([0-9A-Fa-f]{2})$
                  type: string
                  description: 'The MAC address of the desk phone. Note: If you''re using a wireless phone, enter the wired MAC address, not the wireless MAC address.'
                  example: 543968a78ee7
                model:
                  maxLength: 50
                  type: string
                  description: The model name of the device.
                  example: testModel
                type:
                  maxLength: 50
                  type: string
                  description: The manufacturer (brand) name of the device.
                  example: DeviceBrand
                provision_template_id:
                  type: string
                  description: The provision template ID. Supported only by some devices. Empty string represents 'No value set'.
                  example: Ke5Ghevvoo001hr
                site_id:
                  type: string
                  description: The site ID required when adding an unassigned device with multi-site functionality enabled.
                  example: 9gCxz-nKTzuLBWrMx3lNQw
      responses:
        '201':
          description: "**HTTP Status Code:** `201` **Created**  \n \nDevice added successfully.  "
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The unique identifier of the desk phone.
                    example: Q3ECfhVES-uS4mew-161rg
                  display_name:
                    type: string
                    description: The display name of the desk phone.
                    example: Desk Phone
        '400':
          description: "**HTTP Status Code:** `400` <br>\n Bad Request  \n\n **Error Code:** `300` <br>\n Validation failed. <br>\n**Error Code:** `405` <br>\n The number of items for `assignee_extension_ids` must not exceed 10. <br>\n"
        '404':
          description: "**HTTP Status Code:** `404` <br>\n Not Found  \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/rate-limits/). \n\n "
      security:
      - openapi_oauth:
        - phone:write:admin
        - phone:write:device:admin
        openapi_authorization: []
      x-extensions:
        x-permissions: []
        x-macro-scopes:
        - phone:write:admin
        x-granular-scopes:
        - phone:write:device:admin
  /phone/devices/sync:
    post:
      tags:
      - Phone Devices
      summary: Sync deskphones
      description: 'Use this API to resync all online zero-touch or assisted-provisioning devices in an account or a site. Only allows sending one request every 15 minutes.


        **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:sync_device:admin`


        **[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `Heavy`'
      operationId: syncPhoneDevice
      requestBody:
        content:
          application/json:
            schema:
              required:
              - level
              type: object
              properties:
                level:
                  maximum: 2
                  minimum: 1
                  type: integer
                  description: 'Deskphone sync level: 1 - account level, 2 - site level.'
                  example: 2
                site_id:
                  maxLength: 50
                  type: string
                  description: Site ID.
                  example: NjHmTu16Qfe8yOiNJuekXA
      responses:
        '204':
          description: '**HTTP Status Code:** `204` **No Content** Device resync command issued.'
        '400':
          description: "**HTTP Status Code:** `400` <br>\n Bad Request\n\n**Error Code:** `300` <br>\n\n\n**Error Code:** `429` <br>\nToo many concurrent requests. A request has already been made.\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:sync_device:admin
        openapi_authorization: []
      x-extensions:
        x-macro-scopes:
        - phone:write:admin
        x-granular-scopes:
        - phone:write:sync_device:admin
  /phone/devices/{deviceId}:
    get:
      tags:
      - Phone Devices
      summary: Get device details
      description: 'Returns detailed information about a specific [desk phone device](https://support.zoom.us/hc/en-us/articles/360021119092).


        **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:read:admin`


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


        **[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `LIGHT`'
      operationId: getADevice
      parameters:
      - name: deviceId
        in: path
        description: The unique Identifier of the device.
        required: true
        schema:
          type: string
          example: -tDdYIstSumpA0L13GztIQ
      responses:
        '200':
          description: '**HTTP Status Code:** `200` **OK**


            Device information retrieved successfully.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  assignee:
                    type: object
                    properties:
                      extension_number:
                        type: integer
                        description: The extension number of the Zoom Phone the `user` or `commonArea` uses.
                        format: int64
                        example: 123
                      id:
                        type: string
                        description: The ID of the user or common area to whom the device has been assigned.
                        example: i242djsgrg
                      name:
                        type: string
                        description: Name.
                        example: Pooja
                      extension_type:
                        type: string
                        description: The type of the assignee. It's available only if the device is assigned.
                        example: user
                        enum:
                        - user
                        - commonArea
                    description: The user to whom the device has been assigned.
                  assignees:
                    type: array
                    items:
                      type: object
                      properties:
                        extension_number:
                          type: integer
                          description: The extension number of the Zoom Phone the `user` or `commonArea` uses.
                          format: int64
                          example: 123
                        id:
                          type: string
                          description: The ID of the user or common area to whom the device has been assigned.
                          example: i242djsgrg
                        name:
                          type: string
                          description: The name.
                          example: Pooja
                        extension_type:
                          type: string
                          description: The type of the assignee. It's available only if the device is assigned.
                          example: user
                          enum:
                          - user
                          - commonArea
                        extension_id:
                          type: string
                          description: The extension ID of the `user` or `common area`.
                          example: bdkfdler
                  device_type:
                    type: string
                    description: This field includes the manufacturer name and the model name.
                    example: Ribbon EdgeMarc302
                  display_name:
                    type: string
                    description: The display name of the device.
                    example: Pooja's Phone
                  id:
                    type: string
                    description: The unique identifier of the device.
                    example: '1234324'
                  mac_address:
                    type: string
                    description: The MAC address or serial number of the device.
                    example: 203a07240534
                  provision:
                    type: object
                    properties:
                      sip_accounts:
                        type: array
                        description: 'The SIP Account details registered during the device provisioning process. This object will only be returned if manual provisioning was used for the device.  '
                        items:
                          type: object
                          properties:
                            authorization_id:
                              type: string
                              description: The authorization ID of the SIP account provided in the provisioning process.
                              example: '123123'
                            outbound_proxy:
                              type: string
                              description: The outbound proxy provided in the provisioning process.
                              example: '123123'
                            password:
                              type: string
                              description: 'The password entered during the provisioning process. '
                              example: '1123'
                            secondary_outbound_proxy:
                              type: string
                              description: The secondary outbound proxy provided in the provisioning process.
                              example: proxy.example.com:5555
                            shared_line:
                              type: object
                              properties:
                                alias:
                                  type: string
                                  description: The alias.
                                  example: additional information
                                line_subscription:
                                  type: object
                                  properties:
                                    display_name:
                                      type: string
                                      description: The display name.
                                      example: Pooja
                                    extension_number:
                                      type: integer
                                      description: The extension number.
                                      format: int64
                                      example: 123123
                                    phone_number:
                                      type: string
                                      description: The phone number.
                                      example: '12059535689'
                                  description: Line subscription.
                                outbound_caller_id:
                                  type: string
                                  description: The outbound caller ID.
                                  example: '+123123123'
                              description: This field returns additional provisioning information with generic device SIP credentials.
                            sip_domain:
                              type: string
                              description: "The SIP domain provided in the provisioning process.  \n  \n "
                              example: 123.zoom.us
                            user_name:
                              type: string
                              description: The user name of the SIP account provided in the provisioning process.
                              example: '123123'
                      type:
                        type: string
                        description: "The [provisioning type](https://support.zoom.us/hc/en-us/articles/360033223411). The value can be one of the following:\n\n* `ztp` : Zero touch provisioning.\n* `assisted`: Assisted provisioning.\n* `manual`: Manual provisioning. \n\n"
                        example: manual
                        enum:
                        - assisted
                        - ztp
                        - manual
                      url:
                        type: string
                        description: The provisioning URL. This field will only be returned for devices that were provisioned via `assisted` provisioning type.
                        example: wwww.example.com
                    description: The provisioning information of a device.
                  site:
                    type: object
                    properties:
                      id:
                        type: string
                        description: The [site](https://support.zoom.us/hc/en-us/articles/360020809672) of the phone user.
                        example: '123123'
                      name:
                        type: string
                        description: The name of the [site](https://support.zoom.us/hc/en-us/articles/360020809672).
                        example: Main Site
                  status:
                    type: string
                    description: The status of the device. The value is either `online` or `offline`.
                    example: offline
                    enum:
                    - online
                    - offline
                  provision_template_id:
                    type: string
                    description: The provision template ID. Supported only by some devices. Empty string represents 'No value set'
                    example: Ke5Ghevvoo001hr
                  private_ip:
                    type: string
                    description: The private IP of the registered device
                    example: 192.168.10.13
                  public_ip:
                    type: string
                    description: The public IP of the registered device
                    example: 220.148.231.126
                  policy:
                    type: object
                    properties:
                      call_control:
                        type: object
                        properties:
                          status:
                            type: string
                            description: "This field enables the call control feature to the current device. It configures the desk phone devices to enable call control, which allows users to perform desk phone's call control actions from the Zoom desktop client, including making and accepting calls. \nOptions include: \n* `unsupported` \n* `on` \n* `off`"
                            example: 'off'
                            enum:
                            - unsupported
                            - 'on'
                            - 'off'
                      hot_desking:
                        type: object
                        properties:
                          status:
                            type: string
                            description: "This field enables the hot desking feature to the current device. It lets the guest user sign in to the desk phone. You can't use the desk phone until the guest user signs out. \nOptions include:\n* `unsupported` \n* `on` \n* `off`"
                            example: 'off'
                            enum:
                            - unsupported
                            - 'on'
                            - 'off'
                    description: The device policy.
        '400':
          description: "**HTTP Status Code:** `400` <br>\n Bad Request  \n\n **Error Code:** `400` <br>\n Device does not exist in the system. <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:device:admin
        openapi_authorization: []
      x-extensions:
        x-permissions: []
        x-macro-scopes:
        - phone:read:admin
        x-granular-scopes:
        - phone:read:device:admin
    delete:
      tags:
      - Phone Devices
      summary: Delete a device
      description: 'Remove a [desk phone device or ATA (Analog Telephone Adapter)](https://support.zoom.us/hc/en-us/articles/36002111

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