openapi: 3.0.0
info:
  title: Webex Admin Address Book Partner Reports/Templates 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: Partner Reports/Templates
paths:
  /partner/reports:
    get:
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportCollectionResponse'
        '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 previously generated from a given region. Use query parameters to filter the response. The parameters are optional.


        To access this endpoint, you must use an administrator token with `spark-admin:reports_read` and `identity:people_read` scopes.


        <div><Callout type="info">CSV reports for Webex suite services are only supported for organizations based in one region per API request. Organizations based in a different region will require a separate request with region specified.</Callout></div>


        <div><Callout type="info">When no region is specified, the request defaults to Partner organization''s home region.</Callout></div>


        <div><Callout type="info">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.</Callout></div>'
      tags:
      - Partner Reports/Templates
      parameters:
      - 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: '2024-05-01'
        schema:
          type: string
      - name: to
        in: query
        description: List reports that were created before this date.
        example: '2024-05-05'
        schema:
          type: string
      - name: regionId
        in: query
        description: Data in the report will be from organizations in this region, for example, US, CA, or EU.
        example: US
        schema:
          type: string
      - name: onBehalfOfSubPartnerOrgId
        in: query
        description: The encoded organization ID for the sub partner.
        example: Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi8wZTE4MmUxNS05ZmNhLTQ0NzgtYmEzOC1jNGFiMmUyN2FlZDA=
        schema:
          type: string
    post:
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                type: object
                properties:
                  reportId:
                    type: string
                    example: Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mYzhjMWFhMS00OTM5LTQ2NjEtODAwMy1hYWE0MzFmZWM0ZmE
                    description: The unique identifier for the report.
                  createdTime:
                    type: string
                    example: '2024-05-27 17:02:43'
                    description: The time of report creation.
              example:
                reportId: Y2lzY29zcGFyazovL3VybjpURUFNOnVzLWVhc3QtMV9pbnQxMy9SRVBPUlQvYWQwZDIwNTc1ZGEwNDVhNDhmYWQ0N2Q5NzRhYjQxZjI
                createdTime: '2024-05-27 17:02:43'
        '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. A new report can be created using `templateId` available from the _List Report Templates_ API. For each `templateId`, there are a set of validation rules that need to be followed.


        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.


        To access this endpoint, you must use an administrator token with `spark-admin:reports_write` and `identity:people_read` scopes.


        **Notes**:


        <div><Callout type="info">CSV reports for Webex suite services are only created for organizations in the specified region. Organizations based in a different region will require a separate request with region specified.</Callout></div>


        <div><Callout type="info">When no region is specified, the request defaults to Partner organization''s home region. A request against a region where there are no organizations will return blank CSV files.</Callout></div>'
      tags:
      - Partner Reports/Templates
      parameters:
      - name: onBehalfOfSubPartnerOrgId
        in: query
        description: The encoded organization ID for the sub partner.
        example: Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi8wZTE4MmUxNS05ZmNhLTQ0NzgtYmEzOC1jNGFiMmUyN2FlZDA=
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              templateId: 5
              startDate: '2024-05-01'
              endDate: '2024-05-05'
              regionId: US
            schema:
              type: object
              required:
              - templateId
              - startDate
              - endDate
              properties:
                templateId:
                  type: number
                  example: 5
                  description: Unique ID representing valid report templates.
                startDate:
                  type: string
                  example: '2024-05-01'
                  description: Data in the report will be from this date onwards.
                endDate:
                  type: string
                  example: '2024-05-05'
                  description: Data in the report will be until this date.
                regionId:
                  type: string
                  example: US
                  description: Data in the report will be from organizations in this region, for example, US, CA, or EU.
  /partner/reports/{reportId}:
    get:
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report'
              example:
                reportId: Y2lzY29zcGFyazovL3VybjpURUFNOnVzLWVhc3QtMV9pbnQxMy9SRVBPUlQvYWQwZDIwNTc1ZGEwNDVhNDhmYWQ0N2Q5NzRhYjQxZjI
                templateId: 5
                title: Calling Usage Reports
                service: Teams
                startDate: '2024-02-23'
                endDate: '2024-03-24'
                regionId: US
                createdTime: '2024-03-24 17:13:39'
                status: done
                fileName: Calling Usage_12345_Org_2024-05-01_2024-05-05.csv
                fileSize: 0
                checksum: '12345'
                downloadURL: https://downloadservicebts.webex.com/api?reportId=Y2lzY29zcGFyazovL3VzL1JFUE9SVC9hZDBkMjA1NzVkYTA0NWE0OGZhZDQ3ZDk3NGFiNDFmMg
                downloadUrlExpiryTime: '3600'
        '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.


        To access this endpoint, you must use an administrator token with `spark-admin:reports_read` and `identity:people_read` scopes.


        **Notes**:


        <div><Callout type="info">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.</Callout></div>'
      tags:
      - Partner Reports/Templates
      parameters:
      - name: reportId
        in: path
        description: The unique identifier for the report.
        required: true
        example: Y2lzY29zcGFyazovL3VybjpURUFNOnVzLWVhc3QtMV9pbnQxMy9SRVBPUlQvYWQwZDIwNTc1ZGEwNDVhNDhmYWQ0N2Q5NzRhYjQxZjI
        schema:
          type: string
      - name: onBehalfOfSubPartnerOrgId
        in: query
        description: The encoded organization ID for the sub partner.
        example: Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi8wZTE4MmUxNS05ZmNhLTQ0NzgtYmEzOC1jNGFiMmUyN2FlZDA=
        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


        To access this endpoint, you must use an administrator token with `spark-admin:reports_write` scope.'
      tags:
      - Partner Reports/Templates
      parameters:
      - name: reportId
        in: path
        description: The unique identifier for the report.
        required: true
        example: Y2lzY29zcGFyazovL3VybjpURUFNOnVzLWVhc3QtMV9pbnQxMy9SRVBPUlQvYWQwZDIwNTc1ZGEwNDVhNDhmYWQ0N2Q5NzRhYjQxZjI
        schema:
          type: string
      - name: onBehalfOfSubPartnerOrgId
        in: query
        description: The encoded organization ID for the sub partner.
        example: Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi8wZTE4MmUxNS05ZmNhLTQ0NzgtYmEzOC1jNGFiMmUyN2FlZDA=
        schema:
          type: string
  /partner/reports/templates:
    get:
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateCollectionResponse'
              example:
              - templateId: 130
                title: Calling Usage
                service: Teams
                category: Partner
                maxDays: 31
                dataStartDate: '2024-01-01'
                dataEndDate: '2024-01-31'
        '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 Report Templates
      operationId: listReportTemplates
      description: 'List report templates. Report templates are available for use with the Partner Reports API.


        To access this endpoint, you must use an administrator token with `spark-admin:reports_read` and `identity:people_read` [scopes](/docs/integrations#scopes). The authenticated user must be a Partner full administrator or Partner read-only administrator of the organization.'
      tags:
      - Partner Reports/Templates
      parameters:
      - name: onBehalfOfSubPartnerOrgId
        in: query
        description: The encoded organization ID for the sub partner.
        example: Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi8wZTE4MmUxNS05ZmNhLTQ0NzgtYmEzOC1jNGFiMmUyN2FlZDA=
        schema:
          type: string
components:
  schemas:
    Template:
      type: object
      properties:
        id:
          type: string
          example: '130'
          description: Unique identifier representing a report.
        title:
          type: string
          example: Client Version
          description: Name of the template.
        service:
          type: string
          example: Teams
          description: The service to which the report belongs.
        maxDays:
          type: number
          example: 31
          description: Maximum date range for reports belonging to this template.
        identifier:
          type: string
          example: orgWithoutDate
          description: Generated reports belong to which field.
        validations:
          $ref: '#/components/schemas/ValidationRulesCollection'
    ReportCollectionResponse:
      type: object
      properties:
        Report Attributes:
          type: array
          items:
            $ref: '#/components/schemas/Report'
          description: An array of report objects.
    ValidationRulesCollection:
      type: object
      properties:
        validations:
          type: array
          items:
            $ref: '#/components/schemas/ValidationRules'
          description: An array of validation rules
    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.
    TemplateCollectionResponse:
      type: object
      properties:
        Template Collection:
          type: array
          items:
            $ref: '#/components/schemas/Template'
          description: An array of template objects.
    ValidationRules:
      type: object
      properties:
        field:
          type: string
          example: templateId
          description: Field on which validation rule is applied
        required:
          type: string
          example: 'yes'
          description: Whether the above field is required
  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