Cisco Voice Portal Reporting API

openapi: 3.1.0
info:
  title: Cisco Voice Portal Reporting API
  description: >-
    The Cisco Unified Customer Voice Portal (CVP) Reporting API provides access
    to call detail records (CDRs), real-time call statistics, and historical
    reporting data. The Reporting Server collects data from CVP Call Servers and
    VXML Servers, storing it in the CVP Reporting Database (an Informix
    database). This API provides RESTful access to reporting data that is
    typically accessed via the Cisco Unified Intelligence Center (CUIC)
    reporting interface.
  version: 12.6.0
  contact:
    name: Cisco Developer Support
    url: https://developer.cisco.com/
  license:
    name: Cisco DevNet
    url: https://developer.cisco.com/site/license/
  x-provider: cisco
  x-product: unified-customer-voice-portal
servers:
- url: https://{reporting-server}:8111/cvp-reporting/rest
  description: CVP Reporting Server REST API
  variables:
    reporting-server:
      default: cvp-reporting.example.com
      description: Hostname or IP of the CVP Reporting Server
paths:
  /cdr:
    get:
      operationId: getCallDetailRecords
      summary: Cisco Voice Portal Query Call Detail Records
      description: >-
        Retrieves call detail records (CDRs) based on specified filter
        criteria. CDRs contain comprehensive information about each call
        processed by CVP including timing, routing decisions, application
        interactions, and outcome.
      tags:
      - Call Detail Records
      parameters:
      - name: startTime
        in: query
        required: true
        description: Start of the query time range (ISO 8601)
        schema:
          type: string
          format: date-time
      - name: endTime
        in: query
        required: true
        description: End of the query time range (ISO 8601)
        schema:
          type: string
          format: date-time
      - name: calledNumber
        in: query
        description: Filter by called number (DNIS)
        schema:
          type: string
      - name: callingNumber
        in: query
        description: Filter by calling number (ANI)
        schema:
          type: string
      - name: callGuid
        in: query
        description: Filter by unique call GUID
        schema:
          type: string
      - name: callResult
        in: query
        description: Filter by call result
        schema:
          type: string
          enum:
          - completed
          - abandoned
          - transferred
          - error
      - name: offset
        in: query
        description: Pagination offset
        schema:
          type: integer
          default: 0
      - name: limit
        in: query
        description: Maximum number of records to return
        schema:
          type: integer
          default: 100
          maximum: 1000
      - name: sortBy
        in: query
        description: Field to sort by
        schema:
          type: string
          default: callStartTime
          enum:
          - callStartTime
          - callEndTime
          - calledNumber
          - callingNumber
      - name: sortOrder
        in: query
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      responses:
        '200':
          description: Call detail records matching the query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CdrQueryResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /cdr/{callGuid}:
    get:
      operationId: getCallDetailRecord
      summary: Cisco Voice Portal Get a Specific Call Detail Record
      description: >-
        Retrieves the complete call detail record for a specific call,
        identified by its globally unique identifier (GUID). Includes all
        call legs, application interactions, and ECC variables.
      tags:
      - Call Detail Records
      parameters:
      - name: callGuid
        in: path
        required: true
        description: Globally unique call identifier
        schema:
          type: string
      responses:
        '200':
          description: Call detail record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallDetailRecord'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /cdr/{callGuid}/legs:
    get:
      operationId: getCallLegs
      summary: Cisco Voice Portal Get Call Legs for a Call
      description: >-
        Retrieves all individual call legs associated with a specific call.
        A call may have multiple legs representing transfers, conferences,
        or application hand-offs within the CVP system.
      tags:
      - Call Detail Records
      parameters:
      - name: callGuid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Call legs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CallLeg'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /statistics/realtime:
    get:
      operationId: getRealtimeStatistics
      summary: Cisco Voice Portal Get Real-time Call Statistics
      description: >-
        Retrieves current real-time statistics across the CVP deployment,
        including active calls, calls per second, and resource utilization
        metrics. Data is refreshed at the reporting server polling interval.
      tags:
      - Real-Time Statistics
      parameters:
      - name: serverId
        in: query
        description: Filter by specific server ID. If omitted, returns aggregate.
        schema:
          type: string
      responses:
        '200':
          description: Real-time statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RealtimeStatistics'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /statistics/summary:
    get:
      operationId: getCallSummaryStatistics
      summary: Cisco Voice Portal Get Call Summary Statistics
      description: >-
        Retrieves aggregated call summary statistics for a specified time
        period, including total calls, average handle time, abandonment
        rate, and self-service completion rate.
      tags:
      - Historical Reports
      parameters:
      - name: startTime
        in: query
        required: true
        schema:
          type: string
          format: date-time
      - name: endTime
        in: query
        required: true
        schema:
          type: string
          format: date-time
      - name: interval
        in: query
        description: Aggregation interval
        schema:
          type: string
          enum:
          - fifteen_minutes
          - thirty_minutes
          - hourly
          - daily
          default: hourly
      - name: calledNumber
        in: query
        description: Filter by called number (DNIS)
        schema:
          type: string
      responses:
        '200':
          description: Summary statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallSummaryStatistics'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /statistics/application:
    get:
      operationId: getApplicationStatistics
      summary: Cisco Voice Portal Get Vxml Application Statistics
      description: >-
        Retrieves usage and performance statistics for deployed VXML
        applications, including invocation counts, completion rates, and
        average interaction duration.
      tags:
      - Historical Reports
      parameters:
      - name: startTime
        in: query
        required: true
        schema:
          type: string
          format: date-time
      - name: endTime
        in: query
        required: true
        schema:
          type: string
          format: date-time
      - name: applicationName
        in: query
        description: Filter by specific application name
        schema:
          type: string
      responses:
        '200':
          description: Application statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationStatistics'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /statistics/server:
    get:
      operationId: getServerStatistics
      summary: Cisco Voice Portal Get Per-server Statistics
      description: >-
        Retrieves call processing statistics broken down by individual CVP
        server, useful for capacity planning and load monitoring.
      tags:
      - Historical Reports
      parameters:
      - name: startTime
        in: query
        required: true
        schema:
          type: string
          format: date-time
      - name: endTime
        in: query
        required: true
        schema:
          type: string
          format: date-time
      - name: serverType
        in: query
        description: Filter by server type
        schema:
          type: string
          enum:
          - CallServer
          - VXMLServer
      responses:
        '200':
          description: Server statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerStatistics'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /report:
    get:
      operationId: listReportTemplates
      summary: Cisco Voice Portal List Available Report Templates
      description: >-
        Retrieves a list of available report templates that can be executed.
        These correspond to the standard CVP reports available in Cisco
        Unified Intelligence Center.
      tags:
      - Report Templates
      responses:
        '200':
          description: List of report templates
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ReportTemplate'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /report/{templateId}/execute:
    post:
      operationId: executeReport
      summary: Cisco Voice Portal Execute a Report Template
      description: >-
        Executes a report template with the specified parameters. Reports
        may be generated synchronously for small datasets or asynchronously
        for large reports.
      tags:
      - Report Templates
      parameters:
      - name: templateId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportExecutionRequest'
      responses:
        '200':
          description: Report results (synchronous)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportResult'
        '202':
          description: Report generation initiated (asynchronous)
          content:
            application/json:
              schema:
                type: object
                properties:
                  reportId:
                    type: string
                  status:
                    type: string
                    enum:
                    - processing
                  estimatedCompletionTime:
                    type: string
                    format: date-time
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /report/{reportId}/result:
    get:
      operationId: getReportResult
      summary: Cisco Voice Portal Get Report Execution Result
      description: >-
        Retrieves the result of a previously executed report. For
        asynchronous reports, returns the result once generation is complete.
      tags:
      - Report Templates
      parameters:
      - name: reportId
        in: path
        required: true
        schema:
          type: string
      - name: format
        in: query
        description: Output format
        schema:
          type: string
          enum:
          - json
          - csv
          default: json
      responses:
        '200':
          description: Report result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportResult'
            text/csv:
              schema:
                type: string
        '202':
          description: Report still processing
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication using CVP reporting credentials
  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication required or credentials invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Requested resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    CdrQueryResult:
      type: object
      properties:
        totalRecords:
          type: integer
          description: Total number of matching records
          example: 10
        offset:
          type: integer
          example: 10
        limit:
          type: integer
          example: 10
        records:
          type: array
          items:
            $ref: '#/components/schemas/CallDetailRecord'
          example: []
    CallDetailRecord:
      type: object
      properties:
        callGuid:
          type: string
          description: Globally unique call identifier
          example: '500123'
        callStartTime:
          type: string
          format: date-time
          description: Call start timestamp
          example: '2026-01-15T10:30:00Z'
        callEndTime:
          type: string
          format: date-time
          description: Call end timestamp
          example: '2026-01-15T10:30:00Z'
        callingNumber:
          type: string
          description: Caller ANI (Automatic Number Identification)
          example: example_value
        calledNumber:
          type: string
          description: Called DNIS (Dialed Number Identification Service)
          example: example_value
        callResult:
          type: string
          enum:
          - completed
          - abandoned
          - transferred
          - error
          description: Final call outcome
          example: completed
        callDuration:
          type: integer
          description: Total call duration in seconds
          example: 10
        selfServiceDuration:
          type: integer
          description: Duration of self-service (IVR) portion in seconds
          example: 10
        queueDuration:
          type: integer
          description: Duration in queue in seconds
          example: 10
        applicationName:
          type: string
          description: VXML application that handled the call
          example: example_value
        callServerHostname:
          type: string
          description: Call Server that processed the call
          example: example_value
        vxmlServerHostname:
          type: string
          description: VXML Server that executed the application
          example: example_value
        sipCallId:
          type: string
          description: SIP Call-ID header value
          example: '500123'
        icmCallKey:
          type: string
          description: ICM/UCCE call key for correlation
          example: example_value
        eccVariables:
          type: object
          additionalProperties:
            type: string
          description: Expanded Call Context (ECC) variables
          example: example_value
        transferDestination:
          type: string
          description: Transfer destination number if the call was transferred
          example: example_value
        errorCode:
          type: string
          description: Error code if the call ended in error
          example: example_value
    CallLeg:
      type: object
      properties:
        legId:
          type: string
          example: '500123'
        callGuid:
          type: string
          example: '500123'
        legType:
          type: string
          enum:
          - inbound
          - outbound
          - transfer
          - conference
          description: Type of call leg
          example: inbound
        startTime:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
        endTime:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
        duration:
          type: integer
          description: Leg duration in seconds
          example: 10
        fromUri:
          type: string
          description: SIP From URI
          example: example_value
        toUri:
          type: string
          description: SIP To URI
          example: example_value
        serverHostname:
          type: string
          description: Server that handled this leg
          example: example_value
        sipResponseCode:
          type: integer
          description: Final SIP response code for this leg
          example: 10
    RealtimeStatistics:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
        activeCalls:
          type: integer
          description: Current number of active calls
          example: 10
        callsInProgress:
          type: object
          properties:
            selfService:
              type: integer
              description: Calls currently in self-service IVR
            queued:
              type: integer
              description: Calls currently queued
            connected:
              type: integer
              description: Calls connected to agents
          example: example_value
        callsPerSecond:
          type: number
          format: float
          description: Current calls per second rate
          example: 42.5
        peakActiveCalls:
          type: integer
          description: Peak active calls in current period
          example: 10
        serverMetrics:
          type: array
          items:
            type: object
            properties:
              serverId:
                type: string
              hostname:
                type: string
              serverType:
                type: string
              activeCalls:
                type: integer
              cpuUsage:
                type: number
                format: float
              memoryUsage:
                type: number
                format: float
          example: []
    CallSummaryStatistics:
      type: object
      properties:
        startTime:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
        endTime:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
        interval:
          type: string
          example: example_value
        intervals:
          type: array
          items:
            type: object
            properties:
              intervalStart:
                type: string
                format: date-time
              intervalEnd:
                type: string
                format: date-time
              totalCalls:
                type: integer
              completedCalls:
                type: integer
              abandonedCalls:
                type: integer
              transferredCalls:
                type: integer
              errorCalls:
                type: integer
              averageDuration:
                type: number
                format: float
                description: Average call duration in seconds
              averageSelfServiceDuration:
                type: number
                format: float
              selfServiceCompletionRate:
                type: number
                format: float
                description: Percentage of calls completed in self-service
              abandonRate:
                type: number
                format: float
                description: Percentage of abandoned calls
          example: []
    ApplicationStatistics:
      type: object
      properties:
        startTime:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
        endTime:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
        applications:
          type: array
          items:
            type: object
            properties:
              applicationName:
                type: string
              totalInvocations:
                type: integer
              completedInvocations:
                type: integer
              errorInvocations:
                type: integer
              averageDuration:
                type: number
                format: float
                description: Average application interaction duration in seconds
              completionRate:
                type: number
                format: float
              errorRate:
                type: number
                format: float
          example: []
    ServerStatistics:
      type: object
      properties:
        startTime:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
        endTime:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
        servers:
          type: array
          items:
            type: object
            properties:
              serverId:
                type: string
              hostname:
                type: string
              serverType:
                type: string
              totalCalls:
                type: integer
              peakConcurrentCalls:
                type: integer
              averageConcurrentCalls:
                type: number
                format: float
              cpuUsageAverage:
                type: number
                format: float
              memoryUsageAverage:
                type: number
                format: float
          example: []
    ReportTemplate:
      type: object
      properties:
        templateId:
          type: string
          example: '500123'
        name:
          type: string
          example: Example Title
        description:
          type: string
          example: A sample description.
        category:
          type: string
          enum:
          - call_activity
          - application_performance
          - server_performance
          - error_analysis
          example: call_activity
        parameters:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              type:
                type: string
              required:
                type: boolean
              description:
                type: string
          example: []
    ReportExecutionRequest:
      type: object
      properties:
        parameters:
          type: object
          additionalProperties: true
          description: Report parameters as defined by the template
          example: example_value
        format:
          type: string
          enum:
          - json
          - csv
          default: json
          example: json
        async:
          type: boolean
          default: false
          description: Whether to execute asynchronously
          example: true
    ReportResult:
      type: object
      properties:
        reportId:
          type: string
          example: '500123'
        templateId:
          type: string
          example: '500123'
        templateName:
          type: string
          example: example_value
        status:
          type: string
          enum:
          - completed
          - processing
          - error
          example: completed
        generatedAt:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
        parameters:
          type: object
          additionalProperties: true
          example: example_value
        columns:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              type:
                type: string
          example: []
        rows:
          type: array
          items:
            type: array
            items: {}
          example: []
        totalRows:
          type: integer
          example: 10
    Error:
      type: object
      properties:
        code:
          type: string
          example: example_value
        message:
          type: string
          example: example_value
        details:
          type: string
          example: example_value
        timestamp:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
security:
- basicAuth: []
tags:
- name: Call Detail Records
  description: Access and query call detail records
- name: Historical Reports
  description: Aggregated historical reporting data
- name: Real-Time Statistics
  description: Current call processing statistics
- name: Report Templates
  description: Execute pre-defined report templates