Zoom Phone Phone Numbers API

openapi: 3.2.0
info:
  title: Zoom Phone Phone Numbers API
  version: '2'
  contact:
    name: Zoom Developers
    url: https://developer.zoom.us/
  termsOfService: https://zoom.us/docs/en-us/zoom_api_license_and_tou.html
  description: 'Operations tagged Phone Numbers across 2 of this provider''s published API definitions: zoom-phone-api-openapi.json, zoom-phone-number-management-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.zoom.us/v2
tags:
- name: Phone Numbers
paths:
  /phone/byoc_numbers:
    post:
      tags:
      - Phone Numbers
      summary: Add BYOC phone numbers
      description: "Adds BYOC (Bring Your Own Carrier) phone numbers to Zoom Phone.\n\n**Prerequisites** \n* A Business or Enterprise plan \n* A Zoom Phone license\n\n**[Scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-overview/):** `phone:write:admin`\n\n**[Granular Scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-overview/):** `phone:write:byo_carrier_number:admin`\n\n**[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `LIGHT`"
      operationId: addBYOCNumber
      requestBody:
        content:
          application/json:
            schema:
              required:
              - carrier
              - phone_numbers
              type: object
              properties:
                carrier:
                  type: string
                  description: Name of the carrier.
                  example: Bandwidth
                phone_numbers:
                  maxItems: 50
                  type: array
                  description: Phone number(s) to be added to Zoom. The value should be in e164 format.
                  items:
                    type: string
                    example: '+8618251885564'
                sip_group_id:
                  type: string
                  description: Sip group id.
                  example: GgyGPoRESCKAD8JpGXjJ8w
                site_id:
                  type: string
                  description: Unique identifier of the site. This field is only required if you have enabled multiple sites in the account. See [Managing multiple sites](https://support.zoom.us/hc/en-us/articles/360020809672-Managing-multiple-sites) or [Adding a site](https://support.zoom.us/hc/en-us/articles/360020809672-Managing-multiple-sites#h_05c88e35-1593-491f-b1a8-b7139a75dc15) for details.
                  example: 8f71O6rWT8KFUGQmJIFAdQ
      responses:
        '201':
          description: '**HTTP Status Code:** `201` **Created**'
          content:
            application/json:
              schema:
                type: object
                properties:
                  phone_numbers:
                    maxItems: 50
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Unique identifier of the phone number.
                          example: LzPlp8GwR6iytydAq2luIg
                        number:
                          type: string
                          description: Phone number in e164 format.
                          example: '8618251885565'
        '400':
          description: "**HTTP Status Code:** `400` <br>\n Bad Request  \n\n **Error Code:** `300` <br>\n Validation failed. <br>\n**Error Code:** `400` <br>\n Batch phone numbers are limited to 50 per request. <br>\n"
        '401':
          description: "**HTTP Status Code:** `401` <br>\n Unauthorized  \n\n **Error Code:** `124` <br>\n Account does not exist: {accountId}. <br>\n"
        '404':
          description: "**HTTP Status Code:** `404` <br>\n Not Found  \n\n **Error Code:** `404` <br>\n The following account carrier does not exist: {0}. <br>\n"
        '429':
          description: "**HTTP Status Code:** `429` <br>\n Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/). \n\n "
      deprecated: true
      security:
      - openapi_oauth:
        - phone:write:admin
        - phone:write:byo_carrier_number:admin
        openapi_authorization: []
      x-extensions:
        x-permissions: []
        x-macro-scopes:
        - phone:write:admin
        x-granular-scopes:
        - phone:write:byo_carrier_number:admin
    servers:
    - url: https://api.zoom.us/v2
  /phone/numbers:
    get:
      tags:
      - Phone Numbers
      summary: List phone numbers
      description: "Returns a list all Zoom Phone numbers in a Zoom account.\n\n**Prerequisites:** \n* A Pro or higher account plan \n* A Zoom Phone license\n\n**[Scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-overview/):** `phone:read:admin`\n\n**[Granular Scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-overview/):** `phone:read:list_numbers:admin`\n\n**[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `MEDIUM`"
      operationId: listAccountPhoneNumbers
      parameters:
      - 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: type
        in: query
        description: "The query response by number assignment. The value can be one of the following:\n  \n \n`assigned`: The number has been assigned to either a user, a call queue, an auto-receptionist, or a common area in an account.   \n `unassigned`: The number is not assigned to anyone.  \n \n`all`: Include both assigned and unassigned numbers in the response.  \n \n`byoc`: Include Bring Your Own Carrier (BYOC) numbers only in the response."
        required: false
        schema:
          type: string
          example: all
          enum:
          - assigned
          - unassigned
          - byoc
          - all
      - name: extension_type
        in: query
        description: "The type of assignee to whom the number is assigned. The parameter can be set only if `type` parameter is set as `assigned`. The value can be one of the following:  \n \n`user`  \n  `callQueue`  \n  `autoReceptionist`  \n `commonArea`  \n `emergencyNumberPool`  \n `companyLocation`  \n `meetingService`"
        required: false
        schema:
          type: string
          example: user
          enum:
          - user
          - callQueue
          - autoReceptionist
          - commonArea
          - emergencyNumberPool
          - companyLocation
          - meetingService
      - name: page_size
        in: query
        description: The number of records returned within a single API call.
        required: false
        schema:
          maximum: 100
          type: integer
          example: 30
          default: 30
      - name: number_type
        in: query
        description: The type of phone number. The value can be either `toll` or `tollfree`.
        required: false
        schema:
          type: string
          example: toll
          enum:
          - toll
          - tollfree
      - name: pending_numbers
        in: query
        description: This field includes or excludes pending numbers in the response. The value can be either `true` or `false`.
        required: false
        schema:
          type: boolean
          example: false
      - 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](https://support.zoom.us/hc/en-us/articles/360020809672-Managing-multiple-sites) or [Adding a site](https://support.zoom.us/hc/en-us/articles/360020809672-Managing-multiple-sites#h_05c88e35-1593-491f-b1a8-b7139a75dc15) for details.
        required: false
        schema:
          type: string
          example: 8f71O6rWT8KFUGQmJIFAdQ
      - name: phone_number
        in: query
        description: The phone number in E164 format.
        required: false
        schema:
          type: string
          example: '+12008001005'
      responses:
        '200':
          description: "**HTTP Status Code:** `200` **OK**  \n \nPhone numbers listed successfully."
          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 returns whenever the set of available results exceeds the current page size. The expiration period for this token is 15 minutes.)
                    example: bkOcmnm6mn6ioYAi10BcgRiEL38WzAo6jP2
                  page_size:
                    type: integer
                    description: The number of records returned within a single API call.
                    example: 30
                  phone_numbers:
                    type: array
                    items:
                      type: object
                      properties:
                        assignee:
                          type: object
                          properties:
                            extension_number:
                              type: integer
                              description: The extension number of the phone.
                              format: int64
                              example: 1000001101
                            id:
                              type: string
                              description: The unique identifier of the user to whom the number has been assigned.
                              example: Y40mS72DRamFgGh0V1Ul_Q
                            name:
                              type: string
                              description: The name of the user to whom the number has been assigned.
                              example: User Name
                            type:
                              type: string
                              description: "This field indicates to whom the phone number belongs.  \n \n`user`: Number has been assigned to an existing phone user that allows them to receive calls through their extension number or direct phone number.  \n  `callQueue`: Phone number has been assigned to a [call queue](https://support.zoom.us/hc/en-us/articles/360021524831-Managing-Call-Queues).  \n `autoReceptionist`: Phone number has been assigned to an [auto receptionist](https://support.zoom.us/hc/en-us/articles/360021121312-Managing-Auto-Receptionists-and-Integrated-Voice-Response-IVR-).  \n `commonArea`: Phone number has been assigned to a [common area](https://support.zoom.us/hc/en-us/articles/4481136653709-May-2022-New-Common-Area-Experience).  \n  `emergencyNumberPool` `companyLocation` `meetingService`"
                              example: user
                              enum:
                              - user
                              - callQueue
                              - autoReceptionist
                              - commonArea
                              - emergencyNumberPool
                              - companyLocation
                              - meetingService
                              - sharedLineGroup
                        capability:
                          type: array
                          description: The capability for the phone number, whether it can take incoming calls, make outgoing calls, or both. Values include `incoming`, `outgoing`, or both values.
                          items:
                            type: string
                            example: incoming
                        carrier:
                          type: object
                          properties:
                            code:
                              type: integer
                              description: The carrier code.
                              example: 1
                            name:
                              type: string
                              description: The name of the carrier to which the phone number is assigned.
                              example: Bandwidth
                          description: This field displays when the `type` request parameter is `byoc`.
                        display_name:
                          type: string
                          description: The display name for the phone number.
                          example: abc
                        emergency_address:
                          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 consists of the house number and street name.
                              example: 55 ALMADEN BLVD
                            address_line2:
                              type: string
                              description: Address Line 2 of the [emergency address](https://support.zoom.us/hc/en-us/articles/360021062871-Setting-an-Emergency-Address) that consists of building number, floor number, unit and so on.
                              example: test 7
                            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 (Aplha-2 code in ISO-3166 format) standard 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: This field displays when the `type` request parameter is `byoc`.
                        emergency_address_status:
                          type: integer
                          description: 'This field displays when the `type` request parameter is `byoc`. The emergency address status: `1`-carrier update required, `2`-confirmed'
                          example: 1
                          enum:
                          - 1
                          - 2
                        emergency_address_update_time:
                          type: string
                          description: 'This field displays when the `type` request parameter is `byoc`. The time of emergency address information update (format: ''yyyy-MM-ddThh:dd:ssZ'').'
                          example: '2022-02-18T07:20:19Z'
                        id:
                          type: string
                          description: The unique identifier of the phone number.
                          example: aMy7P9DMS9iNRkpwXNfRbw
                        location:
                          type: string
                          description: The location (city, state and country) where the phone number is assigned.
                          example: United States
                        number:
                          type: string
                          description: The phone number in E164 format.
                          example: '+12008001005'
                        number_type:
                          type: string
                          description: "The type of number. Values can be one of the following:  \n \n`toll`, `tollfree`"
                          example: toll
                          enum:
                          - toll
                          - tollfree
                        sip_group:
                          type: object
                          properties:
                            display_name:
                              type: string
                              description: The name of the SIP group.
                              example: RRRR
                            id:
                              type: string
                              description: The ID of the SIP group. See the **Creating SIP groups** section in [Creating a shared directory of external contacts](https://support.zoom.us/hc/en-us/articles/360037050092-Creating-a-shared-directory-of-external-contacts) for details.
                              example: 8MhK7ea4Q4ihIQ4TD_g0kw
                          description: This field displays when the `type` request parameter is `byoc`.
                        site:
                          type: object
                          properties:
                            id:
                              type: string
                              description: The target [site](https://support.zoom.us/hc/en-us/articles/360020809672-Managing-Multiple-Sites) in which the phone number was assigned. Sites allow you to organize the phone users in your organization. For example, you sites could be created based on different office locations.
                              example: 8f71O6rWT8KFUGQmJIFAdQ
                            name:
                              type: string
                              description: The name of the site where the phone number is assigned.
                              example: Main Site
                        source:
                          type: string
                          description: The source of the phone number.
                          example: external
                          enum:
                          - internal
                          - external
                        status:
                          type: string
                          description: The status of the number.
                          example: available
                          enum:
                          - pending
                          - available
                  total_records:
                    type: integer
                    description: The total number of records returned.
                    example: 50
        '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 "
      deprecated: true
      security:
      - openapi_oauth:
        - phone:read:admin
        - phone:read:list_numbers:admin
        openapi_authorization: []
      x-extensions:
        x-permissions: []
        x-macro-scopes:
        - phone:read:admin
        x-granular-scopes:
        - phone:read:list_numbers:admin
    delete:
      tags:
      - Phone Numbers
      summary: Delete unassigned phone numbers
      description: "Deletes unassigned [phone numbers](https://support.zoom.us/hc/en-us/articles/360020808292-Managing-Phone-Numbers#h_38ba8b01-26e3-4b1b-a9b5-0717c00a7ca6). Up to 20 phone numbers can be removed in a single request.\n\n**Prerequisites:** \n* A Business or Enterprise account \n* A Zoom Phone license \n* The user must have been previously assigned a Zoom Phone number\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:delete:number:admin`\n\n**[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `MEDIUM`"
      operationId: deleteUnassignedPhoneNumbers
      parameters:
      - name: phone_numbers
        in: query
        description: Comma seperated list of unassigned phone numbers in E164 format or phone number IDs.
        required: true
        schema:
          maxItems: 20
          minItems: 1
          type: array
          items:
            type: string
            example: 8_RkKw9OQ42oYsXqJJjs4A
      responses:
        '204':
          description: '**HTTP Status Code:** `204`

            The Phone numbers successfully removed.'
        '400':
          description: "**HTTP Status Code:** `400` <br>\n Bad Request  \n\n **Error Code:** `300` <br>\n The number of items for the query parameter `phone_numbers` must be between 1 and 20 inclusive. <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 "
      deprecated: true
      security:
      - openapi_oauth:
        - phone:write:admin
        - phone:delete:number:admin
        openapi_authorization: []
      x-extensions:
        x-permissions: []
        x-macro-scopes:
        - phone:write:admin
        x-granular-scopes:
        - phone:delete:number:admin
    servers:
    - url: https://api.zoom.us/v2
  /phone/numbers/sites/{siteId}:
    patch:
      tags:
      - Phone Numbers
      summary: Update a site's unassigned phone numbers
      description: "Updates a site's unassigned [phone numbers](https://support.zoom.us/hc/en-us/articles/360020808292-Managing-Phone-Numbers#h_38ba8b01-26e3-4b1b-a9b5-0717c00a7ca6). Up to 20 phone numbers can be updated in a single request. \n\n**Prerequisites:** \n* A Pro or higher account plan \n* A Zoom Phone license\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:update:site_number:admin`\n\n**[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `Medium`"
      operationId: updateSiteForUnassignedPhoneNumbers
      parameters:
      - name: siteId
        in: path
        description: Unique identifier of the site
        required: true
        schema:
          type: string
          example: 8f71O6rWT8KFUGQmJIFAdQ
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                phone_numbers:
                  maxItems: 20
                  type: array
                  description: The phone number ID or a phone number in E164 format.
                  items:
                    type: string
                    example: 8_RkKw9OQ42oYsXqJJjs4A
      responses:
        '204':
          description: '**HTTP Status Code:** `204` **No Content**



            Site successfully updated.'
        '400':
          description: "**HTTP Status Code:** `400` <br>\n Bad Request\n\n**Error Code:** `300` <br>\n\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:update:site_number:admin
        openapi_authorization: []
      x-extensions:
        x-macro-scopes:
        - phone:write:admin
        x-granular-scopes:
        - phone:update:site_number:admin
    servers:
    - url: https://api.zoom.us/v2
  /phone/numbers/{phoneNumberId}:
    get:
      tags:
      - Phone Numbers
      summary: Get a phone number
      description: "Returns information about an account's Zoom Phone number.\n\n**Prerequisites:** \n* A Pro or higher account plan \n* A Zoom phone license\n\n**[Scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-overview/):** `phone:read:admin`\n\n**[Granular Scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-overview/):** `phone:read:numbers:admin`\n\n**[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `LIGHT`"
      operationId: getPhoneNumberDetails
      parameters:
      - name: phoneNumberId
        in: path
        description: The unique identifier of the phone number retrieved from the List phone numbers API.
        required: true
        schema:
          type: string
          example: iHE1MQAET2iV85MbfaQmwg
      responses:
        '200':
          description: "**HTTP Status Code:** `200` **OK**  \n \nPhone number details retrieved successfully."
          content:
            application/json:
              schema:
                type: object
                properties:
                  assignee:
                    type: object
                    properties:
                      audio_prompt_language:
                        type: string
                        example: en-GB
                      display_number:
                        type: string
                        description: This field indicates the meeting service, defines the format, and displays the number in meeting invitations and emails.
                        example: display_name_123
                      extension_number:
                        type: integer
                        description: The extension number of the phone.
                        format: int64
                        example: 1000001101
                      greeting:
                        type: object
                        properties:
                          id:
                            type: string
                            description: The audio prompt file ID. If the audio was removed from the user's audio library, it will be marked with a prefix, `removed_vWby3OZaQlS1nAdmEAqgwA` for example. You can still use this audio ID to get the audio information in the [Get an audio item](https://marketplace.zoom.us/docs/api-reference/phone/methods#tag/Audio-Library/operation/GetAudioItem) API.
                            example: 4CRwFZtVTa67JcfO37iQqA
                          name:
                            type: string
                            description: The audio prompt file name.
                            example: TestName
                        description: This field indicates the meeting service. You can only upload one audio file. The accepted format is .wav (also 8k, mono, ULAW or ALAW). If no audio file uploads, Zoom uses the &quot;Telephone welcome message&quot; setting in account settings.
                      id:
                        type: string
                        description: 'The ID of the user. The following are assigned: emergency number pool (if the account has multiple sites enabled, the ID is `siteId`, else `accountId`), and company location. '
                        example: rYgfsrduSXWCxr94poMN5g
                      label:
                        type: string
                        description: 'Optional. This field indicates the meeting service. This label will be appended to the number in parentheses, and will appear in meeting invitations and the zoom client. Formatting rules:

                          Maximum 32 characters

                          Do not use digits

                          Do not use characters &quot;(&quot; &quot;)&quot; &quot;,&quot; &quot;;&quot; or &quot;:&quot;'
                        example: abcd
                      meeting_id:
                        type: string
                        description: The meeting ID for the meeting service.
                        example: abcd
                      name:
                        type: string
                        description: The name of the user to whom the number, emergency number pool, and company location are assigned.
                        example: Test name
                      on_hold_music:
                        type: object
                        properties:
                          id:
                            type: string
                            description: The audio prompt file ID. If the audio was removed from the user's audio library, it will be marked with a prefix, `removed_vWby3OZaQlS1nAdmEAqgwA` for example. You can use this audio ID to get the audio information in the [Get an audio item](https://marketplace.zoom.us/docs/api-reference/phone/methods#tag/Audio-Library/operation/GetAudioItem) API.
                            example: 4CRwFZtVTa67JcfO37iQqA
                          name:
                            type: string
                            description: The audio prompt file name.
                            example: Audio1
                        description: This field indicates the meeting service. You can only upload one audio file. The accepted format is .wav (also 8k, mono, ULAW or ALAW). If no audio file uploads, Zoom uses the &quot;Telephone on-hold music&quot; setting in account settings.
                      type:
                        type: string
                        description: "This field indicates to whom the phone number belongs.  \n \n`user`: Number has been assigned to an existing phone user and allows them to receive calls through their extension number or direct phone number.  \n  `callQueue`: Phone number has been assigned to a [call queue](https://support.zoom.us/hc/en-us/articles/360021524831-Managing-Call-Queues).  \n \n`autoReceptionist`: Phone number has been assigned to an [auto receptionist](https://support.zoom.us/hc/en-us/articles/360021121312-Managing-Auto-Receptionists-and-Integrated-Voice-Response-IVR-).  \n \n`commonArea`: Phone number has been assigned to a common area(https://support.zoom.us/hc/en-us/articles/4481136653709-May-2022-New-Common-Area-Experience).  \n  `emergencyNumberPool` `companyLocation` `meetingService`"
                        example: user
                        enum:
                        - user
                        - callQueue
                        - autoReceptionist
                        - commonArea
                        - emergencyNumberPool
                        - companyLocation
                        - meetingService
                  capability:
                    type: array
                    description: "The capability of the phone number to receive incoming calls, make outgoing calls, or both. \n\nValues are `incoming`, `outgoing`, or both values."
                    items:
                      type: string
                      example: incoming
                  carrier:
                    type: object
                    properties:
                      code:
                        type: integer
                        description: The  carrier code.
                        example: 2
                      name:
                        type: string
                        description: The carrier name.
                        example: Inteliquent
                  display_name:
                    type: string
                    description: The display name of the phone number.
                    example: Display name
                  emergency_address:
                    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 consists of the house number and street name.
                        example: 55 ALMADEN BLVD
                      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 consists of the building number, floor number, unit, and so on.
                        example: test 7
                      city:
                        type: string
                        description: The city of the [emergency address](https://support.zoom.us/hc/en-us/articles/360021062

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