Zoom Phone Reports API

openapi: 3.2.0
info:
  title: Phone Reports 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: Reports
paths:
  /phone/reports/call_charges:
    get:
      tags:
      - Reports
      summary: Get call charges usage report
      description: "Retrieves the Phone Call Charges Report. \n\nThe Call charges usage report allows account owners and admins to view monthly Zoom phone call charges. Account owners and admins can also access this information when they log into their Zoom accounts and navigate to [Call Charges Usage Report](https://zoom.us/pbx/page/report/system#/report/phone-system/charge?page_size=15&chargeRestrict=0&by=1).\n\n **Prerequisites:** \n\n* Account must be enrollled in Pro or a higher plan\n* Account must be enrolled in a [Zoom Phone](https://zoom.us/pricing/zoom-phone) plan\n\n\n\n**[Scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-overview/):** `phone:read:admin`\n\n**[Granular Scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-overview/):** `phone:read:call_charges:admin`\n\n**[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `HEAVY`"
      operationId: GetCallChargesUsageReport
      parameters:
      - 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 from date should not exceed recent 13 months. If unspecified, it 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. The end time and date in **yyyy-mm-dd** or **yyyy-MM-dd''T''HH:mm:ss''Z''** format is the same format as the `from` parameter.'
        required: false
        schema:
          type: string
          format: date
          example: '2021-12-31'
      - name: page_size
        in: query
        description: The number of records to be returned within a single API call. The default is **30** and the maximum is **300**.
        required: false
        schema:
          type: integer
          example: 30
      - name: next_page_token
        in: query
        description: The next page token paginates through a large set of results. A next page token returns whenever the set of available results exceeds the current page size. The expiration period for this token is 15 minutes..
        required: false
        schema:
          type: string
          example: cWiI3vTqdcENiV9RJz3Rh8iP1ksNPheW8c1
      - name: billing_account_id
        in: query
        description: The billing account ID.
        required: false
        schema:
          type: string
          example: 3WWAEiEjTj2IQuyDiKMd_A
      - name: show_charges_only
        in: query
        description: This field shows calls with charges only. The default value is `false`.
        required: false
        schema:
          type: boolean
          example: false
      - name: call_ids
        in: query
        description: The call IDs to filter the call charge report. The maximum limit is 100.
        required: false
        schema:
          type: string
          example: 069e986d5006516028c,069e6d3ec00650201c6
      responses:
        '200':
          description: '**HTTP Status Code:** `200`


            Call charges returned.'
          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: BJLYC6PABbAHdjwSkGVQeeR6B1juwHqj3G2
                  page_size:
                    maximum: 300
                    type: integer
                    description: 'The given page size. '
                    example: 20
                    default: 30
                  total_records:
                    type: integer
                    description: The total number of records returned within a single API call.
                    example: 10
                  from:
                    type: string
                    description: The start time and date of the call.
                    example: '2021-10-01'
                  to:
                    type: string
                    description: The end time and date of the SMS/MMS.
                    example: '2021-10-12'
                  call_charges:
                    maxItems: 300
                    type: array
                    description: An array of call charges
                    items:
                      type: object
                      properties:
                        charge_id:
                          type: string
                          description: The call charge's unique identifier.
                          example: 20260411-21sf18-e1a8-4211-119e-14ce313a9eac
                        call_log_id:
                          type: string
                          description: The ID of the call log. You can use this value to fetch the details of the call log using [Get call log details](https://developers.zoom.us/docs/api/rest/reference/phone/methods/#operation/getCallLogDetails).
                          example: 1csf78-e9a8-4e14-859e-94ce323a9eef
                          deprecated: true
                        call_id:
                          type: string
                          description: The call ID of the charge report.
                          example: 069e986d5006516028c
                        direction:
                          type: string
                          description: The direction of the call.
                          example: inbound
                          enum:
                          - inbound
                          - outbound
                        caller_number:
                          type: string
                          description: The caller's phone number.
                          example: '1001'
                        caller_billing_number:
                          type: string
                          description: The caller's billing phone number.
                          example: '+2100000980'
                        caller_billing_number_type:
                          type: string
                          description: The caller's billing phone number type.
                          example: voip
                          enum:
                          - fixed_line
                          - mobile
                          - fixed_line_or_mobile
                          - toll_free
                          - premium_rate
                          - shared_cost
                          - voip
                          - personal_number
                          - pager
                          - uan
                          - voicemail
                          - unknown
                        callee_number:
                          type: string
                          description: The callee's phone number.
                          example: '1008'
                        callee_billing_number:
                          type: string
                          description: The callee's billing phone number.
                          example: '+21058945728'
                        callee_billing_number_type:
                          type: string
                          description: The callee's billing phone number type.
                          example: toll_free
                          enum:
                          - fixed_line
                          - mobile
                          - fixed_line_or_mobile
                          - toll_free
                          - premium_rate
                          - shared_cost
                          - voip
                          - personal_number
                          - pager
                          - uan
                          - voicemail
                          - unknown
                        call_type:
                          type: string
                          description: 'The type of call:

                            * `voip` (Voice over IP)

                            * `local` (Public Switched Telephone Network)

                            * `tollfree`

                            * `international`

                            * `callCenter`'
                          example: voip
                          enum:
                          - voip
                          - local
                          - tollfree
                          - international
                          - callCenter
                        service_type:
                          type: string
                          description: "The type of service:\n* `meeting` \n* `call` (normal call)`"
                          example: call
                          enum:
                          - meeting
                          - call
                        calling_party_name:
                          type: string
                          description: The name of the calling party.
                          example: User
                        cost_center:
                          type: string
                          description: The name of the cost center.
                          example: Phone cost center
                        employee_id:
                          type: string
                          description: The employee's ID.
                          example: A9877
                        department:
                          type: string
                          description: The name of the department.
                          example: Engineering
                        start_time:
                          type: string
                          description: The call start time in GMT `date-time` format.
                          example: '2021-10-08T16:01:15Z'
                        answer_time:
                          type: string
                          description: The call answer time in GMT `date-time` format.
                          example: '2021-10-08T16:02:15Z'
                        end_time:
                          type: string
                          description: The call end time in GMT `date-time` format.
                          example: '2021-10-08T16:12:15Z'
                        duration:
                          type: integer
                          description: The duration of the call in minutes.
                          example: 1
                        charge_mode:
                          type: string
                          description: The mode of charging.
                          example: per_min
                          enum:
                          - per_min
                          - per_call
                          - per_call_per_min
                          - per_min_after_t_duration
                          - per_call_per_min_after_t_duration
                          x-enum-descriptions:
                          - per minute
                          - per call
                          - per call and per minute
                          - per minute after t duration
                          - per call and per minute after t
                        rate:
                          type: string
                          description: The rate of billing.
                          example: '0.0205'
                        currency:
                          type: string
                          description: The currency of the billed amount.
                          example: USD
                        total_charge:
                          type: string
                          description: The total charge.
                          example: '0'
                        billing_number:
                          type: string
                          description: The billing number.
                          example: 2100000980 Ext. 1001
                        forward_number_billing:
                          type: string
                          description: The billing for the forward number.
                          example: '2100000980'
        '400':
          description: "**HTTP Status Code:** `400` <br>\n Bad Request  \n\n **Error Code:** `400` <br>\n The next page token is invalid or expired. <br>\n**Error Code:** `400` <br>\n The billing_account_id is invalid. <br>\n**Error Code:** `400` <br>\n Invalid start date. Report is provided only for recent 13 months. <br>\n"
        '404':
          description: "**HTTP Status Code:** `404` <br>\n Not Found  \n\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:admin
        - phone:read:call_charges:admin
        openapi_authorization: []
      x-extensions:
        x-permissions: []
        x-macro-scopes:
        - phone:read:admin
        x-granular-scopes:
        - phone:read:call_charges:admin
  /phone/reports/fax_charges:
    get:
      tags:
      - Reports
      summary: Get fax charges usage report
      description: "Retrieves the Phone Fax Charges Report. The fax charges usage report allows account owners and admins to view monthly Zoom phone fax charges. \n\nAccount owners and admins can also access this information when they log into their Zoom accounts and navigate to [Fax Charges Usage Report](https://zoom.us/pbx/page/report/system#/report/phone-system/charge?page_size=15&amp;by=3). \n\n**Prerequisites** \n* Account must be enrollled in Pro or a higher plan\n* Account must be enrolled in a [Zoom Phone](https://zoom.us/pricing/zoom-phone) plan\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:fax_charges:admin`\n\n**[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `HEAVY`"
      operationId: Getfaxchargesusagereport
      parameters:
      - 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 from date should not exceed recent 13 months. If unspecified, it returns data from the past 30 days.
        required: false
        schema:
          type: string
          example: '2021-12-01'
      - name: to
        in: query
        description: '**Required** only when the `from` parameter is specified. The end time and date in **yyyy-mm-dd** or **yyyy-MM-dd''T''HH:mm:ss''Z''** format is the same format as the `from` parameter.'
        required: false
        schema:
          type: string
          example: '2021-12-31'
      - name: page_size
        in: query
        description: The number of records to be returned within a single API call. The default is 30 and the maximum is 300.
        required: false
        schema:
          type: integer
          example: 30
      - name: next_page_token
        in: query
        description: The next page token paginates through a large set of results. A next page token returns whenever the set of available results exceeds the current page size. The expiration period for this token is 15 minutes.
        required: false
        schema:
          type: string
          example: cWiI3vTqdcENiV9RJz3Rh8iP1ksNPheW8c1
      - name: fax_id
        in: query
        description: The fax ID is used to filter the charge of a specific fax within the period.
        required: false
        schema:
          type: string
          example: FD361623719B460388970623D2AB808A
      responses:
        '200':
          description: '**HTTP Status Code:** `200` Fax charges returned.'
          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: BJLYC6PABbAHdjwSkGVQeeR6B1juwHqj3G2
                  page_size:
                    type: integer
                    description: 'The given page size. '
                    example: 30
                  total_records:
                    type: integer
                    description: The total number of records returned within a single API call.
                    example: 10
                  from:
                    type: string
                    description: The start time and date of the fax.
                    example: '2025-06-01'
                  to:
                    type: string
                    description: The end time and date of the fax.
                    example: '2025-06-30'
                  fax_charges:
                    type: array
                    description: An array of fax charges.
                    items:
                      type: object
                      properties:
                        fax_id:
                          type: string
                          description: The fax ID.
                          example: FD361623719B460388970623D2AB808A
                        sender_number:
                          type: string
                          description: The sender's phone number.
                          example: '+2100000980'
                        receiver_number:
                          type: string
                          description: The receiver's phone number.
                          example: '+21058945728'
                        billing_number:
                          type: string
                          description: The billing phone number.
                          example: '+21058945728'
                        end_time:
                          type: string
                          description: The fax end time in ISO 8601 GMT (UTC) date-time format.
                          example: '2025-07-02T15:51:00Z'
                        charge_mode:
                          type: string
                          description: The mode of charging.
                          example: per_page
                          enum:
                          - per_page
                        fax_type:
                          type: string
                          description: The type of fax.
                          example: international
                          enum:
                          - local
                          - international
                        unlimited:
                          type: boolean
                          description: 'Whether the fax usage for this record is included in unlimited faxing available with certain plans. More details: [Understanding Online Fax licensing](https://support.zoom.com/hc/en/article?id=zm_kb&sysparm_article=KB0080618#mcetoc_1iq1lcq3n18)

                            '
                          example: false
                        total_pages:
                          type: integer
                          description: The total pages.
                          example: 5
                        rate:
                          type: string
                          description: The rate of billing.
                          example: '0.0406'
                        currency:
                          type: string
                          description: 'The currency of the billed amount. Following the [[ISO 4217](https://www.iso.org/iso-4217-currency-codes.html)] standard, such as ''USD'' for US dollars. '
                          example: USD
                        currency_sign:
                          type: string
                          description: The display symbol associated with the currency. It's used for presentation purposes only. This field is optional and should not be used for currency identification or calculation logic.
                          example: $
                        charge_status:
                          type: string
                          description: 'The charge status.

                            * `pending`: the charge has not been calculated yet. The values of `charged_pages` and `total_charge` are not available. They will be determined at the end of the billing cycle.

                            * `calculated`: the charge has been calculated, and the values of `charged_pages` and `total_charge` are available.'
                          example: calculated
                          enum:
                          - pending
                          - calculated
                        charged_pages:
                          type: integer
                          description: The charged pages. Only present when `charge_status` is 'calculated'.
                          example: 5
                        total_charge:
                          type: string
                          description: The total charge. Only present when `charge_status` is 'calculated'.
                          example: '0.203'
        '400':
          description: "**HTTP Status Code:** `400` <br>\n Bad Request  \n\n **Error Code:** `400` <br>\n The next page token is invalid or expired. <br>\n**Error Code:** `400` <br>\n Invalid from/to time. <br>\n"
        '404':
          description: "**HTTP Status Code:** `404` <br>\n Not Found  \n\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/rate-limits/). \n\n "
      security:
      - openapi_oauth:
        - phone:read:admin
        - phone:read:fax_charges:admin
        openapi_authorization: []
      x-extensions:
        x-permissions: []
        x-macro-scopes:
        - phone:read:admin
        x-granular-scopes:
        - phone:read:fax_charges:admin
  /phone/reports/operationlogs:
    get:
      tags:
      - Reports
      summary: Get operation logs report
      description: "Retrieves the phone system operation logs report.\n\nThe phone system operation logs report allows account owners and admins to view monthly Zoom phone related admin operation details. \n\n Account owners and admins can also access this information by logging into their Zoom accounts and navigating to [Phone System Operation Logs](https://zoom.us/pbx/page/report/operations#/report/operation-logs).  \n   \n  **Prerequisites:**   \n \n* Account must be enrollled in Pro or a higher plan\n* Account must be enrolled in a [Zoom Phone](https://zoom.us/pricing/zoom-phone) plan\n\n\n\n**[Scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-overview/):** `phone:read:admin`\n\n**[Granular Scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-overview/):** `phone:read:operation_logs:admin`\n\n**[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `HEAVY`"
      operationId: getPSOperationLogs
      parameters:
      - name: from
        in: query
        description: The start time and date in **yyyy-mm-dd**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. If unspecified, returns data within the 24 hours.
        required: false
        schema:
          type: string
          format: date
          example: '2020-11-01'
      - name: to
        in: query
        description: '**Required** only when the `from` parameter is specified. The end time and date is in **yyyy-mm-dd** format; the same format as the `from` parameter.'
        required: false
        schema:
          type: string
          format: date
          example: '2021-12-31'
      - name: category_type
        in: query
        description: "This field filters the response by the category of the action performed. By default, the value of this field is &quot;all&quot; and thus, the response will include log of all operations for the defined period.  \n   \n To only include response for a specific category type, provide a value for `category_type` from this [table](https://marketplace.zoom.us/docs/api-reference/other-references/phone-operation-categories)."
        required: false
        schema:
          type: string
          example: all
          default: all
      - name: page_size
        in: query
        description: The number of records returned within a single API call.
        required: false
        schema:
          maximum: 300
          type: integer
          example: 30
          default: 30
      - name: next_page_token
        in: query
        description: The next page token paginates through large set of results. A next page token returns whenever the set of available results exceeds the current page size. The expiration period for this token is 15 minutes.
        required: false
        schema:
          type: string
          example: BJLYC6PABbAHdjwSkGVQeeR6B1juwHqj3G2
      responses:
        '200':
          description: "**HTTP Status Code:** `200`  \n \nReport returned."
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  properties:
                    next_page_token:
                      type: string
                      description: The next page token paginates through a large set of result. A next page token returns whenever the set of the available result list exceeds the page size. The expiration period is 15 minutes.
                      example: BJLYC6PABbAHdjwSkGVQeeR6B1juwHqj3G2
                    page_size:
                      maximum: 300
                      type: integer
                      description: 'The amount of records returns within a single API call. '
                      example: 20
                      default: 30
                  description: The pagination object.
                - type: object
                  properties:
                    total_records:
                      type: integer
                      description: The total number of records returned.
                      example: 10
                    from:
                      type: string
                      description: The start time and date of the log.
                      example: '2021-10-01'
                    to:
                      type: string
                      description: The end time and date of the log.
                      example: '2021-10-12'
                - type: object
                  properties:
                    operation_logs:
                      type: array
                      description: The array of operation log objects.
                      items:
                        type: object
                        properties:
                          action:
                            type: string
                            description: The action that was performed.
                            example: ADD
                          category_type:
                            type: string
                            description: The category type of the operation.
                            example: Phone Number
                          operation_detail:
                            type: string
                            description: The Operation details.
                            example: Add BYOC +86 182 5188 5564
                          operator:
                            type: string
                            description: The user who performed the operation.
                            example: user@test.com
                          time:
                            type: string
                            description: The time at which the operation was performed.
                            format: date-time
        '404':
          description: "**HTTP Status Code:** `404` <br>\n Not Found  \n\n **Error Code:** `124` <br>\n Account does not exist: {accountId}. <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:operation_logs:admin
        openapi_authorization: []
      x-extensions:
        x-permissions: []
        x-macro-scopes:
        - phone:read:admin
        x-granular-scopes:
        - phone:read:operation_logs:admin
  /phone/reports/sms_charges:
    get:
      tags:
      - Reports
      summary: Get SMS/MMS charges usage report
      description: 'Retrieves the **SMS/MMS Charges Report**.  The **SMS/MMS charges usage report** allows account owners and admins to view monthly Zoom phone SMS charges. Account owners and admins can also access this information by when they log into their Zoom accounts and navigate to [ SMS/MMS Charges Usage Report](https://zoom.us/pbx/page/report/system#/report/phone-system/charge?page_size=15&amp;chargeRestrict=0&amp;by=2).  **Prerequisites**  * Account must be enrolled in Pro or a higher plan * Account must be enrolled in a [Zoom Phone](https://zoom.us/pricing/zoom-phone) plan


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


        **[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `HEAVY`'
      operationId: GetSMSChargesUsageReport
      parameters:
      - 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 from date should not exceed recent 13 months. If unspecified, it returns data from the past 30 days.
        required: false
        schema:
          type: string
          format: date
          example: '2021-12-01'
      - name: to
        in: query
        description: This field is **required** only when you specify the `from` parameter. End time and date is in a **yyyy-mm-dd** or **yyyy-MM-dd'T'HH:mm:ss'Z'** format.  The `from` parameter uses the the same format.
        required: false
        schema:
          type: string
          format: date
          example: '2021-12-31'
      - name: page_size
        in: query
        description: The number of records to be returned within a single API call. The default is **30**, and the maximum is **300**.
        required: false
        schema:
          type: integer
          example: 30
      - name: next_page_token
        in: query
        description: The next page token paginates through a large set of results. A next page token returns whenever the set of available results exceeds the current page size. The expiration 

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