InfiVoice Analytics API

openapi: 3.2.0
info:
  title: InfiVoice REST Analytics API
  description: Welcome to the InfiVoice REST API documentation. This API enables you to programmatically automate AI-powered voice communications at scale.
  version: 1.0.0
servers:
- url: /api/v1
  description: API v1
security:
- ApiKeyAuth: []
- BearerAuth: []
tags:
- name: Analytics
  description: 'Access aggregated statistics and insights about your calling activity. Use this data to optimize campaigns and measure ROI.


    **Available Metrics:**

    - Total calls and minutes

    - Answer rates and outcomes

    - Average call duration

    - Campaign performance comparisons

    - Daily/weekly/monthly trends'
paths:
  /analytics/calls:
    get:
      summary: Get Call Analytics
      description: 'Retrieve aggregated call statistics. Useful for dashboards and performance monitoring.


        **Metrics Included:**

        - Total calls and minutes

        - Answer rate and average duration

        - Outcome distribution (completed, failed, no-answer)

        - Daily trends


        **Required Scope:** `analytics:read`'
      operationId: getCallAnalytics
      tags:
      - Analytics
      parameters:
      - name: days
        in: query
        description: Number of days to analyze (default 30, max 90)
        schema:
          type: integer
          default: 30
          minimum: 1
          maximum: 90
      responses:
        '200':
          description: Call analytics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallAnalyticsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/campaigns:
    get:
      summary: Get Campaign Analytics
      description: 'Retrieve performance analytics for all campaigns. Compare effectiveness across different campaigns.


        **Metrics Per Campaign:**

        - Total contacts and calls made

        - Answer rate and completion rate

        - Average call duration

        - Cost (credits used)


        **Required Scope:** `analytics:read`'
      operationId: getCampaignAnalytics
      tags:
      - Analytics
      responses:
        '200':
          description: Performance metrics for all campaigns
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignAnalyticsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/summary:
    get:
      summary: Get Analytics Summary
      description: 'Get a high-level summary of all activity. Perfect for executive dashboards and quick status checks.


        **Summary Includes:**

        - Total calls, campaigns, and contacts

        - Credit usage and balance

        - Success rates and key metrics

        - Comparison to previous period


        **Required Scope:** `analytics:read`'
      operationId: getAnalyticsSummary
      tags:
      - Analytics
      parameters:
      - name: days
        in: query
        description: Time period to summarize (default 30 days)
        schema:
          type: integer
          default: 30
      responses:
        '200':
          description: High-level analytics summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsSummaryResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    CampaignAnalyticsResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: array
          items:
            type: object
            properties:
              campaignId:
                type: string
              name:
                type: string
              status:
                type: string
              totalContacts:
                type: integer
              completed:
                type: integer
              successful:
                type: integer
              failed:
                type: integer
              pending:
                type: integer
              successRate:
                type: integer
              startedAt:
                type: string
                format: date-time
              completedAt:
                type: string
                format: date-time
        meta:
          $ref: '#/components/schemas/Meta'
    Meta:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
        timestamp:
          type: string
          format: date-time
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              example: VALIDATION_ERROR
            message:
              type: string
              example: Invalid request parameters
            details:
              type: object
        meta:
          $ref: '#/components/schemas/Meta'
    CallAnalyticsResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            totalCalls:
              type: integer
            completedCalls:
              type: integer
            failedCalls:
              type: integer
            totalDurationMinutes:
              type: integer
            averageDurationSeconds:
              type: integer
            creditsUsed:
              type: number
            period:
              type: object
              properties:
                start:
                  type: string
                  format: date-time
                end:
                  type: string
                  format: date-time
        meta:
          $ref: '#/components/schemas/Meta'
    AnalyticsSummaryResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            period:
              type: object
              properties:
                start:
                  type: string
                  format: date-time
                end:
                  type: string
                  format: date-time
                days:
                  type: integer
            calls:
              type: object
              properties:
                total:
                  type: integer
                completed:
                  type: integer
            campaigns:
              type: object
              properties:
                total:
                  type: integer
                running:
                  type: integer
                completed:
                  type: integer
        meta:
          $ref: '#/components/schemas/Meta'
  responses:
    Unauthorized:
      description: Authentication required or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token (API key)