openapi: 3.0.0
info:
  title: Webex Admin Address Book Reports API
  version: 1.0.0
  description: The Webex Admin APIs provide comprehensive programmatic access to administrative functions for managing Webex organizations, users, licenses, and settings. These APIs enable automation of user provisioning, license assignment, compliance management, and audit event retrieval. Administrators can integrate with enterprise identity systems, enforce security policies, monitor usage, and streamline onboarding/offboarding processes. The APIs support granular control over organizational resources, making them ideal for large-scale deployments and custom admin tooling.
tags:
- name: Reports
paths:
  /reports:
    get:
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportCollectionResponse'
              example:
                items:
                - id: Y2lzY29zcGFyazovL3VzL1JFUE9SVC9hZDBkMjA1NzVkYTA0NWE0OGZhZDQ3ZDk3NGFiNDFmMg
                  service: Teams
                  startDate: '2020-03-17'
                  endDate: '2020-03-18'
                  siteList: ''
                  created: '2020-05-27 17:02:43'
                  createdBy: Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mYzhjMWFhMS00OTM5LTQ2NjEtODAwMy1hYWE0MzFmZWM0ZmE
                  scheduleFrom: api
                  status: done
                  reportTitle: Bots Activity
                  downloadURL: https://downloadservicebts.webex.com/api?reportId=Y2lzY29zcGFyazovL3VzL1JFUE9SVC9hZDBkMjA1NzVkYTA0NWE0OGZhZDQ3ZDk3NGFiNDFmMg
                numberOfReports: 1
        '400':
          description: 'Bad Request: The request was invalid or cannot be otherwise served. An accompanying error message will explain further.'
        '401':
          description: 'Unauthorized: Authentication credentials were missing or incorrect.'
        '403':
          description: 'Forbidden: The request is understood, but it has been refused or access is not allowed.'
        '404':
          description: 'Not Found: The URI requested is invalid or the resource requested, such as a user, does not exist. Also returned when the requested format is not supported by the requested method.'
        '405':
          description: 'Method Not Allowed: The request was made to a resource using an HTTP request method that is not supported.'
        '409':
          description: 'Conflict: The request could not be processed because it conflicts with some established rule of the system. For example, a person may not be added to a room more than once.'
        '410':
          description: 'Gone: The requested resource is no longer available.'
        '415':
          description: 'Unsupported Media Type: The request was made to a resource without specifying a media type or used a media type that is not supported.'
        '423':
          description: 'Locked: The requested resource is temporarily unavailable. A Retry-After header may be present that specifies how many seconds you need to wait before attempting the request again.'
        '428':
          description: 'Precondition Required: File(s) cannot be scanned for malware and need to be force downloaded.'
        '429':
          description: 'Too Many Requests: Too many requests have been sent in a given amount of time and the request has been rate limited. A Retry-After header should be present that specifies how many seconds you need to wait before a successful request can be made.'
        '500':
          description: 'Internal Server Error: Something went wrong on the server. If the issue persists, feel free to contact the [Webex Developer Support team](/explore/support).'
        '502':
          description: 'Bad Gateway: The server received an invalid response from an upstream server while processing the request. Try again later.'
        '503':
          description: 'Service Unavailable: Server is overloaded with requests. Try again later.'
        '504':
          description: 'Gateway Timeout: An upstream server failed to respond on time. If your query uses max parameter, please try to reduce it.'
      summary: List Reports
      operationId: listReports
      description: 'Lists all reports. Use query parameters to filter the response. The parameters are optional. However, `from` and `to` parameters should be provided together.


        **Notes**:

        CSV reports for Webex suite services are only supported for organizations based in the North American region. Organizations based in a different region will return blank CSV files for any Teams reports.


        Reports are usually provided in zip format. A Content-header `application/zip` or `application/octet-stream` does indicate the zip format. There is usually no .zip file extension.'
      tags:
      - Reports
      parameters:
      - name: reportId
        in: query
        description: List reports by ID.
        example: Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mYzhjMWFhMS00OTM5LTQ2NjEtODAwMy1hYWE0MzFmZWM0ZmE
        schema:
          type: string
      - name: service
        in: query
        description: List reports which use this service.
        example: Webex
        schema:
          type: string
      - name: templateId
        in: query
        description: List reports with this report template ID.
        example: 5
        schema:
          type: number
      - name: from
        in: query
        description: List reports that were created on or after this date.
        example: '2020-05-01'
        schema:
          type: string
      - name: to
        in: query
        description: List reports that were created before this date.
        example: '2020-05-05'
        schema:
          type: string
    post:
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mYzhjMWFhMS00OTM5LTQ2NjEtODAwMy1hYWE0MzFmZWM0ZmE
                    description: The unique identifier for the report.
              example:
                items:
                  id: Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mYzhjMWFhMS00OTM5LTQ2NjEtODAwMy1hYWE0MzFmZWM0ZmE
        '400':
          description: 'Bad Request: The request was invalid or cannot be otherwise served. An accompanying error message will explain further.'
        '401':
          description: 'Unauthorized: Authentication credentials were missing or incorrect.'
        '403':
          description: 'Forbidden: The request is understood, but it has been refused or access is not allowed.'
        '404':
          description: 'Not Found: The URI requested is invalid or the resource requested, such as a user, does not exist. Also returned when the requested format is not supported by the requested method.'
        '405':
          description: 'Method Not Allowed: The request was made to a resource using an HTTP request method that is not supported.'
        '409':
          description: 'Conflict: The request could not be processed because it conflicts with some established rule of the system. For example, a person may not be added to a room more than once.'
        '410':
          description: 'Gone: The requested resource is no longer available.'
        '415':
          description: 'Unsupported Media Type: The request was made to a resource without specifying a media type or used a media type that is not supported.'
        '423':
          description: 'Locked: The requested resource is temporarily unavailable. A Retry-After header may be present that specifies how many seconds you need to wait before attempting the request again.'
        '428':
          description: 'Precondition Required: File(s) cannot be scanned for malware and need to be force downloaded.'
        '429':
          description: 'Too Many Requests: Too many requests have been sent in a given amount of time and the request has been rate limited. A Retry-After header should be present that specifies how many seconds you need to wait before a successful request can be made.'
        '500':
          description: 'Internal Server Error: Something went wrong on the server. If the issue persists, feel free to contact the [Webex Developer Support team](/explore/support).'
        '502':
          description: 'Bad Gateway: The server received an invalid response from an upstream server while processing the request. Try again later.'
        '503':
          description: 'Service Unavailable: Server is overloaded with requests. Try again later.'
        '504':
          description: 'Gateway Timeout: An upstream server failed to respond on time. If your query uses max parameter, please try to reduce it.'
      summary: Create a Report
      operationId: createaReport
      description: 'Create a new report. For each `templateId`, there are a set of validation rules that need to be followed. For example, for templates belonging to Webex, the user needs to provide `siteUrl`. These validation rules can be retrieved via the [Report Templates API](/docs/api/v1/report-templates).


        The ''templateId'' parameter is a number. However, it is a limitation of developer.webex.com platform that it is passed as a string when you try to test the API from here.


        CSV reports for Webex suite services are only supported for organizations based in the North American region. Organizations based in a different region will return blank CSV files for any Teams reports.'
      tags:
      - Reports
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - templateId
              properties:
                templateId:
                  type: number
                  example: 5
                  description: Unique ID representing valid report templates.
                startDate:
                  type: string
                  example: '2020-05-01'
                  description: Data in the report will be from this date onwards.
                endDate:
                  type: string
                  example: '2020-05-05'
                  description: Data in the report will be until this date.
                siteList:
                  type: string
                  example: cisco.webex.com
                  description: Sites belonging to user's organization. This attribute is needed for site-based templates.
  /reports/{reportId}:
    get:
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report'
              example:
                id: Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mYzhjMWFhMS00OTM5LTQ2NjEtODAwMy1hYWE0MzFmZWM0ZmE
                title: Bots Activity
                service: Teams
                startDate: '2020-02-23'
                endDate: '2020-03-24'
                siteList: cisco.webex.com
                created: '2020-03-24 17:13:39'
                createdBy: Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mYzhjMWFhMS00OTM5LTQ2NjEtODAwMy1hYWE0MzFmZWM0ZmE
                scheduledFrom: API
                status: done
                downloadURL: https://downloadservicebts.webex.com/api?reportId=Y2lzY29zcGFyazovL3VzL1JFUE9SVC9hZDBkMjA1NzVkYTA0NWE0OGZhZDQ3ZDk3NGFiNDFmMg
        '400':
          description: 'Bad Request: The request was invalid or cannot be otherwise served. An accompanying error message will explain further.'
        '401':
          description: 'Unauthorized: Authentication credentials were missing or incorrect.'
        '403':
          description: 'Forbidden: The request is understood, but it has been refused or access is not allowed.'
        '404':
          description: 'Not Found: The URI requested is invalid or the resource requested, such as a user, does not exist. Also returned when the requested format is not supported by the requested method.'
        '405':
          description: 'Method Not Allowed: The request was made to a resource using an HTTP request method that is not supported.'
        '409':
          description: 'Conflict: The request could not be processed because it conflicts with some established rule of the system. For example, a person may not be added to a room more than once.'
        '410':
          description: 'Gone: The requested resource is no longer available.'
        '415':
          description: 'Unsupported Media Type: The request was made to a resource without specifying a media type or used a media type that is not supported.'
        '423':
          description: 'Locked: The requested resource is temporarily unavailable. A Retry-After header may be present that specifies how many seconds you need to wait before attempting the request again.'
        '428':
          description: 'Precondition Required: File(s) cannot be scanned for malware and need to be force downloaded.'
        '429':
          description: 'Too Many Requests: Too many requests have been sent in a given amount of time and the request has been rate limited. A Retry-After header should be present that specifies how many seconds you need to wait before a successful request can be made.'
        '500':
          description: 'Internal Server Error: Something went wrong on the server. If the issue persists, feel free to contact the [Webex Developer Support team](/explore/support).'
        '502':
          description: 'Bad Gateway: The server received an invalid response from an upstream server while processing the request. Try again later.'
        '503':
          description: 'Service Unavailable: Server is overloaded with requests. Try again later.'
        '504':
          description: 'Gateway Timeout: An upstream server failed to respond on time. If your query uses max parameter, please try to reduce it.'
      summary: Get Report Details
      operationId: getReportDetails
      description: 'Shows details for a report, by report ID.


        Specify the report ID in the `reportId` parameter in the URI.


        **Notes**:

        CSV reports for Webex suite services are only supported for organizations based in the North American region. Organizations based in a different region will return blank CSV files for any Teams reports.


        Reports are usually provided in zip format. A Content-header `application/zip` or `application/octet-stream` does indicate the zip     format. There is usually no .zip file extension.'
      tags:
      - Reports
      parameters:
      - name: reportId
        in: path
        description: The unique identifier for the report.
        required: true
        example: Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mYzhjMWFhMS00OTM5LTQ2NjEtODAwMy1hYWE0MzFmZWM0ZmE
        schema:
          type: string
    delete:
      responses:
        '204':
          description: No Content
          headers: {}
          content: {}
        '400':
          description: 'Bad Request: The request was invalid or cannot be otherwise served. An accompanying error message will explain further.'
        '401':
          description: 'Unauthorized: Authentication credentials were missing or incorrect.'
        '403':
          description: 'Forbidden: The request is understood, but it has been refused or access is not allowed.'
        '404':
          description: 'Not Found: The URI requested is invalid or the resource requested, such as a user, does not exist. Also returned when the requested format is not supported by the requested method.'
        '405':
          description: 'Method Not Allowed: The request was made to a resource using an HTTP request method that is not supported.'
        '409':
          description: 'Conflict: The request could not be processed because it conflicts with some established rule of the system. For example, a person may not be added to a room more than once.'
        '410':
          description: 'Gone: The requested resource is no longer available.'
        '415':
          description: 'Unsupported Media Type: The request was made to a resource without specifying a media type or used a media type that is not supported.'
        '423':
          description: 'Locked: The requested resource is temporarily unavailable. A Retry-After header may be present that specifies how many seconds you need to wait before attempting the request again.'
        '428':
          description: 'Precondition Required: File(s) cannot be scanned for malware and need to be force downloaded.'
        '429':
          description: 'Too Many Requests: Too many requests have been sent in a given amount of time and the request has been rate limited. A Retry-After header should be present that specifies how many seconds you need to wait before a successful request can be made.'
        '500':
          description: 'Internal Server Error: Something went wrong on the server. If the issue persists, feel free to contact the [Webex Developer Support team](/explore/support).'
        '502':
          description: 'Bad Gateway: The server received an invalid response from an upstream server while processing the request. Try again later.'
        '503':
          description: 'Service Unavailable: Server is overloaded with requests. Try again later.'
        '504':
          description: 'Gateway Timeout: An upstream server failed to respond on time. If your query uses max parameter, please try to reduce it.'
      summary: Delete a Report
      operationId: deleteAReport
      description: 'Remove a report from the system.


        Specify the report ID in the `reportId` parameter in the URI


        CSV reports for Webex suite services are only supported for organizations based in the North American region. Organizations based in a different region will return blank CSV files for any Teams reports.'
      tags:
      - Reports
      parameters:
      - name: reportId
        in: path
        description: The unique identifier for the report.
        required: true
        example: Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mYzhjMWFhMS00OTM5LTQ2NjEtODAwMy1hYWE0MzFmZWM0ZmE
        schema:
          type: string
components:
  schemas:
    Report:
      type: object
      properties:
        id:
          type: string
          example: Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mYzhjMWFhMS00OTM5LTQ2NjEtODAwMy1hYWE0MzFmZWM0ZmE
          description: Unique identifier for the report.
        title:
          type: string
          example: Bots Activity
          description: Name of the template to which this report belongs.
        service:
          type: string
          example: Teams
          description: The service to which the report belongs.
        startDate:
          type: string
          example: '2020-02-23'
          description: The data in this report belongs to dates greater than or equal to this.
        endDate:
          type: string
          example: '2020-03-24'
          description: The data in this report belongs to dates smaller than or equal to this.
        siteList:
          type: string
          example: cisco.webex.com
          description: The site to which this report belongs to. This only exists if the report belongs to service `Webex`.
        created:
          type: string
          example: '2020-03-24 17:13:39'
          description: Time of creation for this report.
        createdBy:
          type: string
          example: Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mYzhjMWFhMS00OTM5LTQ2NjEtODAwMy1hYWE0MzFmZWM0ZmE
          description: The person who created the report.
        scheduledFrom:
          type: string
          example: API
          description: Whether this report was scheduled from API or Control Hub.
        status:
          type: string
          example: done
          description: Completion status of this report.
        downloadURL:
          type: string
          example: https://downloadservicebts.webex.com/api?reportId=Y2lzY29zcGFyazovL3VzL1JFUE9SVC9hZDBkMjA1NzVkYTA0NWE0OGZhZDQ3ZDk3NGFiNDFmMg
          description: The link from which the report can be downloaded.
    ReportCollectionResponse:
      type: object
      properties:
        Report Attributes:
          type: array
          items:
            $ref: '#/components/schemas/Report'
          description: An array of report objects.
  securitySchemes:
    oauth2:
      flows:
        authorizationCode:
          authorizationUrl: /
          scopes: {}
          tokenUrl: /
      type: oauth2
    bearer-key:
      type: http
      description: e.g. Bearer YOUR_AUTHORIZATION_TOKEN
      scheme: bearer
      bearerFormat: JWT
    bearerAuth:
      type: oauth2
      description: OAuth 2.0 Bearer token authentication
      flows:
        authorizationCode:
          authorizationUrl: https://webexapis.com/v1/authorize
          tokenUrl: https://webexapis.com/v1/access_token
          scopes:
            spark:applications_token: Create access tokens for Service Apps