Zoom Phone Voicemails API

openapi: 3.2.0
info:
  title: Phone Voicemails 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: Voicemails
paths:
  /phone/call_element/{callElementId}/voice_mail:
    get:
      tags:
      - Voicemails
      summary: Get a voicemail by call element ID
      description: "Returns the detailed information on a voicemail by the call element's `callElementId`.\n**Prerequisites** \n* A Pro or higher account with Zoom Phone license \n* Account owner or admin privileges\n\n**[Scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-overview/):** `phone:read`,`phone:read:admin`,`phone_voicemail:read`,`phone_voicemail:read:admin`\n\n**[Granular Scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-overview/):** `phone:read:voicemail`,`phone:read:voicemail:admin`\n\n**[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `LIGHT`"
      operationId: getVoicemailDetailsByCallElementId
      parameters:
      - name: callElementId
        in: path
        description: The ID of the call element.
        required: true
        schema:
          type: string
          example: 20210609-a297ae04-a875-4cfd-85ab-4adcead91edb
      responses:
        '200':
          description: "**HTTP Status Code:** `200`  \n \nOK."
          content:
            application/json:
              schema:
                type: object
                properties:
                  call_id:
                    type: string
                    description: The phone call ID.
                    example: '876634343743'
                  call_element_id:
                    type: string
                    description: The phone call element's unique ID.
                    example: 20210609-a297ae04-a875-4cfd-85ab-4adcead91edb
                  callee_name:
                    type: string
                    description: The name of the callee.
                    example: Jane Doe
                  callee_number:
                    type: string
                    description: The callee's phone number.
                    example: '34567889'
                  callee_number_type:
                    type: integer
                    description: "The callee's number type: \n* `1` — Internal number. \n* `2` — External number.\n* `3` — Customized emergency number."
                    example: 2
                    enum:
                    - 1
                    - 2
                    - 3
                  caller_name:
                    type: string
                    description: The name of the caller.
                    example: John Doe
                  caller_number:
                    type: string
                    description: The caller's phone number.
                    example: '12345678'
                  caller_number_type:
                    type: integer
                    description: "The caller's number type: \n* `1` — Internal number. \n* `2` — External number."
                    example: 1
                    enum:
                    - 1
                    - 2
                  date_time:
                    type: string
                    description: The date the voicemail was created.
                    example: '2019-05-19T20:00:00Z'
                  download_url:
                    type: string
                    description: "The URL to download the voicemail. For security purposes, you must provide an OAuth access token in the auth header to download the voicemail file using this url.\nExample request:\n```\ncurl --request GET \\\n  --url {download_url} \\\n  --header 'authorization: Bearer {access_token}' \\\n  --header 'content-type: application/json'\n```"
                    example: exampleurl.io
                  duration:
                    type: integer
                    description: The duration of voicemail in seconds.
                    example: 18
                  id:
                    type: string
                    description: The voicemail ID.
                    example: d43520fc6b7e4b26bbeef58a8a80f235
                  status:
                    type: string
                    description: 'The voicemail status: either ''read'' or ''unread''.'
                    example: read
                    enum:
                    - read
                    - unread
                  soft_deleted:
                    type: boolean
                    description: whether this voicemail soft deletes and moves to trash.
                    example: true
                  soft_deleted_type:
                    type: string
                    description: This field indicates how the voicemail was deleted. It exists only when the voicemail is from trash.
                    example: Manual
                    enum:
                    - Manual
                    - Data Retention
                  deleted_time:
                    type: string
                    description: The time and date the voicemail was deleted. It exists only when voicemail is from trash.
                    format: date-time
                    example: '2023-04-18T22:10:49.907Z'
                  days_left_auto_permanently_delete:
                    type: integer
                    description: The number of days left until voicemail is permanently deleted. If the voicemail never auto deletes, the value is '-1'. It exists only when voicemail is from trash.
                    example: 30
                  transcription:
                    type: object
                    properties:
                      content:
                        type: string
                        description: The content of the voicemail transcript.
                        example: some transcript content
                      status:
                        type: integer
                        description: 'The status of the voicemail transcript:

                          * `0` — Transcript is not available.

                          * `1` — Transcript is processing.

                          * `2` — Transcript processed successfully.

                          * `4` — Transcript is disabled.

                          * `5` — Transcript is enabled.

                          * `9` — Transcript web error.

                          * `11` — Transcript download error.

                          * `12` — Transcript upload error.

                          * `13` — Transcript web database error.

                          * `14` — Transcript BYOS (Bring Your Own Storage) upload error.

                          * `409` — Transcript duplicate processing request error.

                          * `415` — Transcript unsupported media error.

                          * `422` — Transcript cannot be processed.

                          * `500` — Transcript server error.

                          * `601` — Transcript AISense after retry error.

                          * `602` — Transcript AISense upload file error.

                          * `603` — Transcript AISense download file error.

                          * `999` — Transcript AISense error.

                          '
                        example: 2
                        enum:
                        - 0
                        - 1
                        - 2
                        - 4
                        - 5
                        - 9
                        - 11
                        - 12
                        - 13
                        - 14
                        - 409
                        - 415
                        - 422
                        - 500
                        - 601
                        - 602
                        - 603
                        - 999
                    description: The voicemail transcript.
                  caller_account_code:
                    type: string
                    description: 'The caller''s account code. To dial between accounts, use the format: [Account code] - [extension number].'
                    example: '111'
                  callee_account_code:
                    type: string
                    description: 'The callee''s account code. To dial between accounts, use the format: [Account code] - [extension number].'
                    example: '222'
                description: The voicemail information.
        '400':
          description: "**HTTP Status Code:** `400` <br>\n Bad Request  \n\n "
        '404':
          description: "**HTTP Status Code:** `404` <br>\n Not Found  \n\n **Error Code:** `404` <br>\n Voicemail does not exist for {callElementId}. <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
        - phone:read:admin
        - phone_voicemail:read
        - phone_voicemail:read:admin
        - phone:read:voicemail
        - phone:read:voicemail:admin
        openapi_authorization: []
      x-extensions:
        x-permissions: []
        x-macro-scopes:
        - phone:read
        - phone:read:admin
        - phone_voicemail:read
        - phone_voicemail:read:admin
        x-granular-scopes:
        - phone:read:voicemail
        - phone:read:voicemail:admin
  /phone/users/{userId}/call_logs/{id}/voice_mail:
    get:
      tags:
      - Voicemails
      summary: Get user voicemail details from a call log
      description: "Returns the detailed information on a voicemail associated with a call log ID. \n\nFor user-level apps, pass [the `me` value](https://marketplace.zoom.us/docs/api-reference/using-zoom-apis#mekeyword) instead of the `userId` parameter.\n\n**Prerequisites** \n* User must belong to a Business or Enterprise account \n* User must have a Zoom Phone license\n\n**[Scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-overview/):** `phone:read`,`phone:read:admin`,`phone_voicemail:read`,`phone_voicemail:read:admin`\n\n**[Granular Scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-overview/):** `phone:read:voicemail`,`phone:read:voicemail:admin`\n\n**[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `LIGHT`"
      operationId: getVoicemailDetailsByCallIdOrCallLogId
      parameters:
      - name: userId
        in: path
        description: The user ID or email address of the user.
        required: true
        schema:
          type: string
          example: IGTRVt3gQ2i-WjoUIjeZxw
      - name: id
        in: path
        description: 'The unique ID of the call log. You can use `callLogId` or `callId` as path parameters.


          You can find the value for this field with in **[Get account''s call logs](https://marketplace.zoom.us/docs/api-reference/phone/methods#operation/accountCallLogs)** API or **[Get user''s call logs](https://marketplace.zoom.us/docs/api-reference/phone/methods#operation/phoneUserCallLogs)** API.'
        required: true
        schema:
          type: string
          example: '46541323465'
      responses:
        '200':
          description: The voicemail information.
          content:
            application/json:
              schema:
                type: object
                properties:
                  call_id:
                    type: string
                    description: The phone call ID.
                    example: '876634343743'
                  call_log_id:
                    type: string
                    description: The call log ID.
                    example: 55fd0af0-beb0-433a-be97-388de5e99ab4
                    deprecated: true
                  call_history_id:
                    type: string
                    example: 20190519-55fd0af0-beb0-433a-be97-388de5e99ab4
                    deprecated: true
                  call_element_id:
                    type: string
                    description: The phone call element's unique ID.
                    example: 20210609-a297ae04-a875-4cfd-85ab-4adcead91edb
                  callee_name:
                    type: string
                    description: The name of the callee.
                    example: Jane Doe
                  callee_number:
                    type: string
                    description: The callee's phone number.
                    example: '34567889'
                  callee_number_type:
                    type: integer
                    description: "The callee's number type: \n* `1` &mdash; Internal number. \n* `2` &mdash; External number.\n* `3` &mdash; Customized emergency number."
                    example: 2
                    enum:
                    - 1
                    - 2
                    - 3
                  caller_name:
                    type: string
                    description: The name of the caller.
                    example: John Doe
                  caller_number:
                    type: string
                    description: The caller's phone number.
                    example: '12345678'
                  caller_number_type:
                    type: integer
                    description: "The caller's number type: \n* `1` &mdash; Internal number. \n* `2` &mdash; External number."
                    example: 1
                    enum:
                    - 1
                    - 2
                  date_time:
                    type: string
                    description: The date the voicemail was created.
                    example: '2019-05-19T20:00:00Z'
                  download_url:
                    type: string
                    description: "The URL to download the voicemail. For security purposes, you must provide an OAuth access token in the auth header to download the voicemail file using this url.\nExample request:\n```\ncurl --request GET \\\n  --url {download_url} \\\n  --header 'authorization: Bearer {access_token}' \\\n  --header 'content-type: application/json'\n```"
                    example: exampleurl.io
                  duration:
                    type: integer
                    description: The duration of voicemail in seconds.
                    example: 18
                  id:
                    type: string
                    description: The voicemail ID.
                    example: d43520fc6b7e4b26bbeef58a8a80f235
                  status:
                    type: string
                    description: 'The voicemail status: either ''read'' or ''unread''.'
                    example: read
                    enum:
                    - read
                    - unread
                  transcription:
                    type: object
                    properties:
                      content:
                        type: string
                        description: The content of the voicemail transcript.
                        example: some transcript content
                      status:
                        type: integer
                        description: 'The status of the voicemail transcript:

                          * `0` &mdash; Transcript is not available.

                          * `1` &mdash; Transcript is processing.

                          * `2` &mdash; Transcript processed successfully.

                          * `4` &mdash; Transcript is disabled.

                          * `5` &mdash; Transcript is enabled.

                          * `9` &mdash; Transcript web error.

                          * `11` &mdash; Transcript download error.

                          * `12` &mdash; Transcript upload error.

                          * `13` &mdash; Transcript web database error.

                          * `14` &mdash; Transcript BYOS (Bring Your Own Storage) upload error.

                          * `409` &mdash; Transcript duplicate processing request error.

                          * `415` &mdash; Transcript unsupported media error.

                          * `422` &mdash; Transcript cannot be processed.

                          * `500` &mdash; Transcript server error.

                          * `601` &mdash; Transcript AISense after retry error.

                          * `602` &mdash; Transcript AISense upload file error.

                          * `603` &mdash; Transcript AISense download file error.

                          * `999` &mdash; Transcript AISense error.

                          '
                        example: 2
                        enum:
                        - 0
                        - 1
                        - 2
                        - 4
                        - 5
                        - 9
                        - 11
                        - 12
                        - 13
                        - 14
                        - 409
                        - 415
                        - 422
                        - 500
                        - 601
                        - 602
                        - 603
                        - 999
                      engine:
                        type: string
                        description: This field indicates the company that provides the transcription engine technology.
                        example: otter
                    description: The voicemail transcript.
                  caller_account_code:
                    type: string
                    description: 'The caller''s account code. To dial between accounts, use the format: [Account code] - [extension number].'
                    example: '111'
                  callee_account_code:
                    type: string
                    description: 'The callee''s account code. To dial between accounts, use the format: [Account code] - [extension number].'
                    example: '222'
                description: The voicemail information.
        '400':
          description: "**HTTP Status Code:** `400` <br>\n Bad Request  \n\n **Error Code:** `300` <br>\n Invalid user id. <br>\n"
        '404':
          description: "**HTTP Status Code:** `404` <br>\n Not Found  \n\n **Error Code:** `404` <br>\n Voice mail does not exist: {0}. <br>\n**Error Code:** `1001` <br>\n User does not exist: {userId}. <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:read
        - phone:read:admin
        - phone_voicemail:read
        - phone_voicemail:read:admin
        - phone:read:voicemail
        - phone:read:voicemail:admin
        openapi_authorization: []
      x-extensions:
        x-permissions: []
        x-macro-scopes:
        - phone:read
        - phone:read:admin
        - phone_voicemail:read
        - phone_voicemail:read:admin
        x-granular-scopes:
        - phone:read:voicemail
        - phone:read:voicemail:admin
  /phone/users/{userId}/voice_mails:
    get:
      tags:
      - Voicemails
      summary: Get user's voicemails
      description: "Returns a user's Zoom Phone voicemails. For user-level apps, pass [the `me` value](https://marketplace.zoom.us/docs/api-reference/using-zoom-apis#mekeyword) instead of the `userId` parameter.\n\n**Prerequisites** \n* A Business or Enterprise account \n* A Zoom Phone license\n\n**[Scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-overview/):** `phone:read`,`phone:read:admin`,`phone_voicemail:read`,`phone_voicemail:read:admin`\n\n**[Granular Scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-overview/):** `phone:read:list_voicemails`,`phone:read:list_voicemails:admin`\n\n**[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `MEDIUM`"
      operationId: phoneUserVoiceMails
      parameters:
      - name: userId
        in: path
        description: The user ID or email address of the user. For user-level apps, pass `me` as the value for userId.
        required: true
        schema:
          type: string
          example: DYHrdpjrS3uaOf7dPkkg8w
      - name: page_size
        in: query
        description: The number of records returned within a single API call.
        required: false
        schema:
          maximum: 300
          type: integer
          example: 30
          default: 30
      - name: status
        in: query
        description: The status of the voice mail.
        required: false
        schema:
          type: string
          example: read
          default: all
          enum:
          - all
          - read
          - unread
      - 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: from
        in: query
        description: The start time and date in **yyyy-mm-dd** or **yyyy-MM-dd'T'HH:mm:ss'Z'** format. The date range defined by the `from` and `to` parameters should be a month as the response only includes one month's worth of data at once. The month defined should fall within the last six months. If unspecified, returns data from the past 30 days.
        required: false
        schema:
          type: string
          format: date
          example: '2021-12-01'
      - name: to
        in: query
        description: '**Required** only when the `from` parameter is specified. End time and date in **yyyy-mm-dd** or **yyyy-MM-dd''T''HH:mm:ss''Z''** format, the same format as the `from` parameter.'
        required: false
        schema:
          type: string
          format: date
          example: '2021-12-31'
      - name: trash
        in: query
        description: Whether to query voicemails from trash.
        required: false
        schema:
          type: boolean
          example: true
      responses:
        '200':
          description: "**HTTP Status Code:** `200`  \n \nUser object returned."
          content:
            application/json:
              schema:
                type: object
                properties:
                  from:
                    type: string
                    description: The start date of the query.
                    format: date
                    example: '2021-05-19'
                  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: VcXBknJ0MQ7kuXun5WKmSjHC1hOBGS2bbr2
                  page_count:
                    type: integer
                    description: The total number of pages.
                    example: 10
                  page_size:
                    type: integer
                    description: The zize of each page.
                    example: 15
                  to:
                    type: string
                    description: The end date.
                    format: date
                    example: '2021-06-19'
                  total_records:
                    type: integer
                    description: The total number of records.
                    example: 150
                  voice_mails:
                    maxItems: 100
                    type: array
                    description: The voicemails.
                    items:
                      type: object
                      properties:
                        call_id:
                          type: string
                          description: The phone call's unique ID.
                          example: '876634343743'
                        call_log_id:
                          type: string
                          description: The phone call log's unique ID.
                          example: 55fd0af0-beb0-433a-be97-388de5e99ab4
                          deprecated: true
                        call_history_id:
                          type: string
                          description: The phone call history's unique ID.
                          example: 20190519-55fd0af0-beb0-433a-be97-388de5e99ab4
                          deprecated: true
                        call_element_id:
                          type: string
                          description: The phone call element's unique ID.
                          example: 20210609-a297ae04-a875-4cfd-85ab-4adcead91edb
                        callee_name:
                          type: string
                          description: The contact name of callee.
                          example: Jane Doe
                        callee_number:
                          type: string
                          description: The number of the callee.
                          example: '34567889'
                        callee_number_type:
                          type: integer
                          description: "The callee's number type: \n* `1` &mdash; Internal number. \n* `2` &mdash; External number.\n* `3` &mdash; Customized emergency number."
                          example: 2
                          enum:
                          - 1
                          - 2
                          - 3
                        caller_name:
                          type: string
                          description: The contact name of the caller.
                          example: John Doe
                        caller_number:
                          type: string
                          description: The number of the caller.
                          example: '12345678'
                        caller_number_type:
                          type: integer
                          description: "The caller's number type: \n* `1` &mdash; Internal number. \n* `2` &mdash; External number."
                          example: 1
                          enum:
                          - 1
                          - 2
                        date_time:
                          type: string
                          description: The time and date the voice mail started.
                          example: '2019-05-19T20:00:00Z'
                        download_url:
                          type: string
                          description: "The download URL of the attachment. For security purposes, you must provide an OAuth access token in the auth header to download the voicemail file using this URL.\nExample request:\n```\ncurl --request GET \\\n  --url {download_url} \\\n  --header 'authorization: Bearer {access_token}' \\\n  --header 'content-type: application/json'\n```"
                          example: exampleurl.io
                        duration:
                          type: integer
                          description: The duration of voicemail in seconds.
                          example: 18
                        id:
                          type: string
                          description: The voicemail ID.
                          example: d43520fc6b7e4b26bbeef58a8a80f235
                        status:
                          type: string
                          description: The status of the voice mail. It can be either 'read' or 'unread'
                          example: read
                          enum:
                          - read
                          - unread
                        caller_account_code:
                          type: string
                          description: 'The caller''s account code. To dial between accounts, use the format: [Account code] - [extension number].'
                          example: '111'
                        callee_account_code:
                          type: string
                          description: 'The callee''s account code. To dial between accounts, use the format: [Account code] - [extension number].'
                          example: '222'
        '400':
          description: "**HTTP Status Code:** `400` <br>\n Bad Request  \n\n **Error Code:** `300` <br>\n Invalid user id. <br>\n**Error Code:** `400` <br>\n The next page token is invalid or expired. <br>\n"
        '404':
          description: "**HTTP Status Code:** `404` <br>\n Not Found  \n\n **Error Code:** `1001` <br>\n User does not exist: {userId}. <br>\n**Error Code:** `2001` <br>\n Account does not exist. <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
        - phone:read:admin
        - phone_voicemail:read
        - phone_voicemail:read:admin
        - phone:read:list_voicemails
        - phone:read:list_voicemails:admin
        openapi_authorization: []
      x-extensions:
        x-permissions: []
        x-macro-scopes:
        - phone:read
        - phone:read:admin
        - phone_voicemail:read
        - phone_voicemail:read:admin
        x-granular-scopes:
        - phone:read:list_voicemails
        - phone:read:list_voicemails:admin
  /phone/voice_mails:
    get:
      tags:
      - Voicemails
      summary: Get account voicemails
      description: "Gets a user's Zoom Phone voicemails. \n\n**Prerequisites** \n* A Business or Enterprise account \n* A Zoom Phone license\n\n**[Scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-overview/):** `phone:read:admin`,`phone_voicemail:read:admin`\n\n**[Granular Scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-overview/):** `phone:read:list_voicemails:admin`\n\n**[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `HEAVY`"
      operationId: accountVoiceMails
      parameters:
      - name: page_size
        in: query
        description: The number of records returned within a single API call.
        required: false
        schema:
          maximum: 300
          type: integer
          example: 30
          default: 30
      - name: status
        in: query
        description: The status of the voice mail.
        required: false
        schema:
          type: string
          example: read
          default: all
          enum:
          - all
          - read
          - unread
      - name: site_id
        in: query
        description: The site ID.
        required: false
        schema:
          type: string
          example: NjHmTu16Qfe8yOiNJuekXA
      - name: owner_type
        in: query
        description: "The owner type. \n\nThe allowed values are `null`, `user`, `callQueue`, `sharedLineGroup`, `autoReceptionist`, or `sharedOffice`(deprecated and to be replaced by `commonArea` after the transition period). \n\nThe default value is `null`.  If the value is `null`, it returns all owner types."
        required: false
        schema:
          type: string
          example: user
          enum:
          - user
          - callQueue
          - sharedLineGroup
          - autoReceptionist
          - commonArea
      - name: voicemail_type
        in: query
        description: The voicemail type.
        required: false
        schema:
          type: string
          example: spam
          enum:
          - normal
          - spam
          - maybeSpam
      - 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 pa

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