openapi: 3.2.0
info:
  title: Customer 360 Interactions Insight API
  description: 'The Customer 360 API provides unified access to customer interaction history and insights across all 8x8 contact center channels.


    Given a customer identity (email, phone number, contact ID, or account ID), the API returns a list of interactions along with aggregated sentiment and topic insights.


    ## Authentication


    All endpoints require an 8x8 API key obtained from the 8x8 Admin Console. Pass the key in the `x-api-key` request header:


    ```

    x-api-key: <your-api-key>

    ```


    Refer to [How to get API Keys](/analytics/docs/how-to-get-api-keys) for instructions on creating an API key.


    ## Regions


    The API is available in four regions. Use the base URL corresponding to the region where your tenant is provisioned:


    | Region | Base URL |

    |---|---|

    | Phoenix (US) | `https://api.8x8.com/cidp-customer-360/us` |

    | London (UK) | `https://api.8x8.com/cidp-customer-360/uk` |

    | Toronto (Canada) | `https://api.8x8.com/cidp-customer-360/ca` |

    | Sydney (Australia) | `https://api.8x8.com/cidp-customer-360/ap` |


    ## Search Strategies


    The API supports four mutually exclusive search strategies. You must provide exactly one identity field per request:


    | Strategy | Required | Optional | Forbidden |

    |---|---|---|---|

    | Contact ID | `contactId`, `crmId` | — | — |

    | Account ID | `accountId` | `crmId` | — |

    | Email | `email` | — | `crmId` |

    | Phone Number | `phoneNumber` | — | `crmId` |


    Only the native CRM is supported. Set `crmId` to `native`.


    ## Time Range


    If `startTime` and `endTime` are omitted, a default window of 1 year ending at the current time is applied. Times must be in ISO-8601 format with timezone (e.g. `2025-08-15T10:30:00-05:00`).


    ## Response Fields


    ### interactions

    A list of individual interactions matching the search criteria. Each interaction includes:

    - `interactionId` — Unique identifier for the interaction

    - `mediaType` — Channel type: `PHONE`, `EMAIL`, `CHAT`, or `VOICEMAIL`

    - `direction` — `INBOUND` or `OUTBOUND`

    - `productType` — 8x8 product that handled the interaction: `CC` (Contact Center), `UC` (Unified Communications), or `ENGAGE`

    - `startedAt` / `endedAt` — Unix epoch milliseconds

    - `sentiment` — Overall sentiment: `POSITIVE`, `NEUTRAL`, or `NEGATIVE`

    - `topics` — List of topics detected in the interaction, each with a name and match count

    - `wrapUpCodes` — Agent wrap-up codes applied at the end of the interaction

    - `queueName` — Name of the queue that handled the interaction

    - `outcomeLabel` — Outcome label assigned to the interaction

    - `interactionLabels` — Labels applied to the interaction


    ### insights

    Aggregated analysis across all returned interactions:

    - `aggregatedSentiments` — Overall customer, agent, and combined sentiment across all interactions

    - `aggregatedTopics` — Topic frequency breakdown showing which topics appeared most often and in what percentage of interactions


    '
  version: '1'
servers:
- url: https://api.8x8.com/cidp-customer-360/us
  description: Phoenix (US)
- url: https://api.8x8.com/cidp-customer-360/uk
  description: London (UK)
- url: https://api.8x8.com/cidp-customer-360/ca
  description: Toronto (Canada)
- url: https://api.8x8.com/cidp-customer-360/ap
  description: Sydney (Australia)
tags:
- name: interactions-insight
  description: Retrieve interaction insights for a customer
paths:
  /v1/public/tenants/{tenantId}/interactions-insight:
    get:
      tags:
      - interactions-insight
      summary: Get interaction insights
      description: 'Retrieves interaction insights for a tenant, including interactions list and speech analytics.


        Supports four search strategies:

        - `contactId` + `crmId` (both required)

        - `accountId` (crmId optional)

        - `email` (crmId must not be provided)

        - `phoneNumber` (crmId must not be provided)


        If `startTime` and `endTime` are omitted, a default time window is applied (1 year).'
      operationId: getInteractionsInsight
      security:
      - ApiKeyAuth: []
      parameters:
      - name: tenantId
        in: path
        required: true
        description: The tenant identifier. Must belong to the authenticated customer.
        schema:
          type: string
        example: acvcc1652172111112801
      - name: contactId
        in: query
        required: false
        description: Contact ID. Requires `crmId` when provided.
        schema:
          type: string
        example: contact-123
      - name: accountId
        in: query
        required: false
        description: Account ID. `crmId` is optional when provided.
        schema:
          type: string
        example: account-456
      - name: email
        in: query
        required: false
        description: Email address. `crmId` must not be provided.
        schema:
          type: string
        example: user@example.com
      - name: phoneNumber
        in: query
        required: false
        description: Phone number in E.164 format. `crmId` must not be provided.
        schema:
          type: string
        example: '+1234567890'
      - name: crmId
        in: query
        required: false
        description: CRM identifier. Required with `contactId`, optional with `accountId`, forbidden with `email`/`phoneNumber`. Only the native CRM is supported.
        schema:
          type: string
        example: native
      - name: startTime
        in: query
        required: false
        description: Start of the time range in ISO-8601 format with timezone offset. Defaults to 1 year before `endTime`.
        schema:
          type: string
          format: date-time
        example: '2025-01-01T00:00:00-00:00'
      - name: endTime
        in: query
        required: false
        description: End of the time range in ISO-8601 format with timezone offset. Defaults to now.
        schema:
          type: string
          format: date-time
        example: '2025-12-31T23:59:59-00:00'
      responses:
        '200':
          description: Successfully retrieved interaction insights
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InteractionsInsight'
              example:
                interactions:
                - interactionId: int-abc123
                  mediaType: CHAT
                  direction: INBOUND
                  startedAt: 1700000000000
                  endedAt: 1700003600000
                  sentiment: POSITIVE
                insights:
                  aggregatedSentiments:
                    totalInteractions: 1
                    aggregatedSentiment:
                      aggregatedCustomerSentiment: POSITIVE
                      aggregatedAgentSentiment: NEUTRAL
                      aggregatedOverallSentiment: POSITIVE
        '400':
          description: Bad request — invalid or missing search criteria
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              example:
                status: 400
                title: Bad Request
                detail: Invalid search criteria
        '401':
          description: Unauthorized — missing or invalid API key
        '403':
          description: Forbidden — tenant does not belong to the authenticated customer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail403'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail500'
components:
  schemas:
    TopicFrequency:
      type: object
      properties:
        topicName:
          type: string
          description: Name of the topic
          example: billing
        categoryName:
          type: string
          description: Category the topic belongs to
          example: Finance
        interactionsMatchedCount:
          type: integer
          format: int32
          description: Number of interactions where this topic was detected
          example: 15
        percentageMatched:
          type: number
          format: double
          description: Percentage of total interactions where this topic was detected
          example: 35.7
    Topic:
      type: object
      properties:
        topic:
          type: string
          description: Topic name
          example: billing
        matches:
          type:
          - integer
          - 'null'
          format: int32
          description: Number of times the topic was matched in the interaction
          example: 3
    Interaction:
      type: object
      properties:
        interactionId:
          type: string
          description: Unique interaction identifier
          example: int-abc123
        contactId:
          type: string
          description: CRM contact identifier associated with the interaction
          example: contact-456
        mediaIdentifier:
          type: string
          description: The customer email or phone number used in this interaction
          example: user@example.com
        mediaType:
          type: string
          description: Channel type of the interaction
          enum:
          - PHONE
          - EMAIL
          - CHAT
          - VOICEMAIL
          example: PHONE
        chatType:
          type: string
          description: Sub-type for chat interactions (e.g. platform or channel variant)
          example: WHATSAPP
        direction:
          type: string
          description: Direction of the interaction
          enum:
          - INBOUND
          - OUTBOUND
          example: INBOUND
        productType:
          type: string
          description: 8x8 product that handled the interaction
          enum:
          - CC
          - UC
          - ENGAGE
          example: CC
        startedAt:
          type: integer
          format: int64
          description: Interaction start time as Unix epoch milliseconds
          example: 1724400000000
        endedAt:
          type: integer
          format: int64
          description: Interaction end time as Unix epoch milliseconds
          example: 1724401800000
        sentiment:
          type: string
          description: Overall sentiment for this interaction
          example: POSITIVE
        topics:
          type: array
          description: Topics detected in this interaction
          items:
            $ref: '#/components/schemas/Topic'
        wrapUpCodes:
          type: array
          description: Agent wrap-up codes applied to the interaction
          items:
            type: string
          example:
          - resolved
          - callback-requested
        queueName:
          type:
          - string
          - 'null'
          description: Name of the queue that handled the interaction
          example: Support Queue
        outcomeLabel:
          type: string
          description: Outcome label assigned to the interaction
          example: Resolved
        interactionLabels:
          type: array
          description: Labels applied to the interaction
          items:
            type: string
          example:
          - vip
          - escalated
        title:
          type:
          - string
          - 'null'
          description: AI-generated title for the interaction (planned for future release, currently null)
        emailSubject:
          type:
          - string
          - 'null'
          description: Email subject line (planned for future release, currently null)
        departmentName:
          type:
          - string
          - 'null'
          description: Department name associated with the interaction (planned for future release, currently null)
        signals:
          type: array
          description: Detected signals from the interaction (planned for future release, currently empty)
          items:
            type: string
    AggregatedTopics:
      type: object
      properties:
        totalInteractions:
          type: integer
          format: int32
          description: Total number of interactions included in the topic aggregation
          example: 42
        topicFrequency:
          type: array
          items:
            $ref: '#/components/schemas/TopicFrequency'
    AggregatedSentiments:
      type: object
      properties:
        totalInteractions:
          type: integer
          format: int32
          description: Total number of interactions included in the aggregation
          example: 42
        aggregatedSentiment:
          $ref: '#/components/schemas/AggregatedSentiment'
    ProblemDetail:
      type: object
      properties:
        status:
          type: integer
          format: int32
          description: HTTP status code
          example: 400
        title:
          type: string
          description: Short description of the error class
          example: Bad Request
        detail:
          type: string
          description: Human-readable explanation of the error
          example: Invalid search criteria
    Insights:
      type: object
      properties:
        aggregatedSentiments:
          $ref: '#/components/schemas/AggregatedSentiments'
        aggregatedTopics:
          $ref: '#/components/schemas/AggregatedTopics'
    InteractionsInsight:
      type: object
      properties:
        interactions:
          type: array
          description: List of interactions matching the search criteria
          items:
            $ref: '#/components/schemas/Interaction'
        insights:
          $ref: '#/components/schemas/Insights'
          description: Aggregated sentiment and topic insights (null if Speech Analytics not licensed)
    AggregatedSentiment:
      type: object
      properties:
        aggregatedCustomerSentiment:
          type: string
          description: Overall aggregated customer sentiment across all interactions
          example: POSITIVE
        aggregatedAgentSentiment:
          type: string
          description: Overall aggregated agent sentiment across all interactions
          example: NEUTRAL
        aggregatedOverallSentiment:
          type: string
          description: Overall aggregated sentiment across all interactions
          example: POSITIVE
    ProblemDetail500:
      type: object
      properties:
        status:
          type: integer
          format: int32
          description: HTTP status code
          example: 500
        title:
          type: string
          description: Short description of the error class
          example: Internal Server Error
        detail:
          type: string
          description: Human-readable explanation of the error
          example: Internal server error
    ProblemDetail403:
      type: object
      properties:
        status:
          type: integer
          format: int32
          description: HTTP status code
          example: 403
        title:
          type: string
          description: Short description of the error class
          example: Forbidden
        detail:
          type: string
          description: Human-readable explanation of the error
          example: Forbidden
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: 8x8 API key obtained from the 8x8 Admin Console.