openapi: 3.0.1
info:
  title: Call Intelligence
  contact:
    name: Bandwidth
    url: https://support.bandwidth.com
    email: support@bandwidth.com
  version: 1.0.0
  termsOfService: https://www.bandwidth.com/legal/terms-of-service/
  description: |-
    The API specification for Bandwidth's Call Intelligence provisioning.

    ## Base URL
    `https://api.bandwidth.com/v2`
servers:
  - url: https://api.bandwidth.com/v2
paths:
  /accounts/{accountId}/call-intelligence/phone-numbers/{phoneNumber}:
    get:
      summary: Get Call Intelligence Settings
      description: Retrieve the Call Intelligence settings for a single phone number.
      operationId: getCallIntelligenceSettings
      tags:
        - Call Intelligence
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/phoneNumber'
      responses:
        '200':
          $ref: '#/components/responses/callIntelligenceSettingsResponse'
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '401':
          $ref: '#/components/responses/unauthorizedResponse'
        '403':
          $ref: '#/components/responses/forbiddenResponse'
        '404':
          $ref: '#/components/responses/notFoundResponse'
        '405':
          $ref: '#/components/responses/methodNotAllowedResponse'
        '429':
          $ref: '#/components/responses/tooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
    put:
      summary: Create or Replace Call Intelligence Settings
      description: >-
        Create or replace Call Intelligence settings on a single phone number.
        This is a synchronous operation.
      operationId: replaceCallIntelligenceSettings
      tags:
        - Call Intelligence
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/phoneNumber'
      requestBody:
        $ref: '#/components/requestBodies/callIntelligenceSettingsRequestBody'
      responses:
        '200':
          $ref: '#/components/responses/callIntelligenceSettingsResponse'
        '201':
          $ref: '#/components/responses/callIntelligenceSettingsCreatedResponse'
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '401':
          $ref: '#/components/responses/unauthorizedResponse'
        '403':
          $ref: '#/components/responses/forbiddenResponse'
        '404':
          $ref: '#/components/responses/notFoundResponse'
        '405':
          $ref: '#/components/responses/methodNotAllowedResponse'
        '429':
          $ref: '#/components/responses/tooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
    delete:
      summary: Delete Call Intelligence Settings
      description: >-
        Delete Call Intelligence settings from a single phone number. This is a
        synchronous operation.
      operationId: deleteCallIntelligenceSettings
      tags:
        - Call Intelligence
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/phoneNumber'
      responses:
        '204':
          $ref: '#/components/responses/noContentResponse'
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '401':
          $ref: '#/components/responses/unauthorizedResponse'
        '403':
          $ref: '#/components/responses/forbiddenResponse'
        '404':
          $ref: '#/components/responses/notFoundResponse'
        '405':
          $ref: '#/components/responses/methodNotAllowedResponse'
        '429':
          $ref: '#/components/responses/tooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
  /accounts/{accountId}/call-intelligence/phone-numbers:
    get:
      summary: List Call Intelligence Settings
      description: >-
        Retrieve Call Intelligence settings for all provisioned phone numbers on
        the account.
      operationId: listCallIntelligenceSettings
      tags:
        - Call Intelligence
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/phoneNumberFilter'
      responses:
        '200':
          $ref: '#/components/responses/listCallIntelligenceSettingsResponse'
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '401':
          $ref: '#/components/responses/unauthorizedResponse'
        '403':
          $ref: '#/components/responses/forbiddenResponse'
        '404':
          $ref: '#/components/responses/notFoundResponse'
        '405':
          $ref: '#/components/responses/methodNotAllowedResponse'
        '429':
          $ref: '#/components/responses/tooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
  /accounts/{accountId}/call-intelligence/phone-numbers/bulk:
    post:
      summary: Bulk Provision Call Intelligence Settings
      description: >
        Submit a request to provision or unprovision Call Intelligence settings
        across multiple phone numbers. This is an asynchronous operation — poll
        `GET
        /accounts/{accountId}/call-intelligence/phone-numbers/bulk/{bulkId}`
        with the returned `bulkId` to check status.


        Processing continues for all phone numbers regardless of individual
        failures. Successfully provisioned numbers are persisted. Check the
        `PARTIAL_SUCCESS` status and the `failed[]` array in the polling
        response for per-number failure details.
      operationId: bulkCreateCallIntelligenceSettings
      tags:
        - Call Intelligence
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        $ref: '#/components/requestBodies/bulkProvisionRequestBody'
      responses:
        '202':
          $ref: '#/components/responses/bulkProvisionAcceptedResponse'
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '401':
          $ref: '#/components/responses/unauthorizedResponse'
        '403':
          $ref: '#/components/responses/forbiddenResponse'
        '404':
          $ref: '#/components/responses/notFoundResponse'
        '405':
          $ref: '#/components/responses/methodNotAllowedResponse'
        '429':
          $ref: '#/components/responses/tooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
  /accounts/{accountId}/call-intelligence/phone-numbers/bulk/{bulkId}:
    get:
      summary: Get Bulk Provision Request Status
      description: >-
        Retrieve the details and current status of a bulk Call Intelligence
        provisioning request.
      operationId: getBulkCallIntelligenceSettingsRequest
      tags:
        - Call Intelligence
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/bulkId'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          $ref: '#/components/responses/bulkStatusResponse'
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '401':
          $ref: '#/components/responses/unauthorizedResponse'
        '403':
          $ref: '#/components/responses/forbiddenResponse'
        '404':
          $ref: '#/components/responses/notFoundResponse'
        '405':
          $ref: '#/components/responses/methodNotAllowedResponse'
        '429':
          $ref: '#/components/responses/tooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
components:
  parameters:
    accountId:
      name: accountId
      in: path
      required: true
      description: The unique account identifier.
      schema:
        type: string
        example: '9999999'
    phoneNumberFilter:
      name: phoneNumber
      in: query
      required: false
      description: Filter parameter for `phoneNumber`.
      style: deepObject
      explode: true
      schema:
        type: object
        properties:
          eq:
            type: string
            description: >-
              Filter to one or more phone numbers in E.164 format, starting with
              '+'. Multiple values are comma-separated for OR matching. Example:
              +19191234567,+19197654321
    phoneNumber:
      name: phoneNumber
      in: path
      required: true
      description: The phone number in E.164 format, starting with '+'.
      schema:
        type: string
        example: '+19191234567'
    bulkId:
      name: bulkId
      in: path
      required: true
      description: The unique identifier of a bulk provisioning request.
      schema:
        type: string
        example: bulk-abc-123
    offset:
      name: offset
      in: query
      required: false
      description: The number of items to skip before returning results. Defaults to 0.
      schema:
        type: integer
        minimum: 0
        default: 0
        example: 0
    limit:
      name: limit
      in: query
      required: false
      description: The maximum number of items to return per page.
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 100
        example: 100
  requestBodies:
    callIntelligenceSettingsRequestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/callIntelligenceSettings'
    bulkProvisionRequestBody:
      required: true
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/bulkProvisionRequest'
              - $ref: '#/components/schemas/bulkUnprovisionRequest'
  schemas:
    originationSettings:
      title: Origination Settings
      description: Call Intelligence settings applied to inbound calls.
      nullable: false
      type: object
      properties:
        recordingEnabled:
          type: boolean
          default: false
          example: true
          description: >
            Indicates if recording is enabled for inbound calls.

            Requires the Call Recording product feature to be enabled on the
            account.
        recordingRedactionEnabled:
          type: boolean
          nullable: true
          default: false
          example: true
          description: |
            Indicates if redaction is enabled for call recordings.
            Requires `recordingEnabled` to be true.
        deleteUnredactedRecording:
          type: boolean
          nullable: true
          default: true
          example: true
          description: >
            Indicates if the unredacted recording should be deleted after
            redaction.

            Requires `recordingRedactionEnabled` to be true.
        transcriptionEnabled:
          type: boolean
          nullable: true
          default: false
          example: true
          description: |
            Indicates if transcription is enabled for inbound call recordings.
            Requires `recordingEnabled` to be true.
        transcriptionRedactionEnabled:
          type: boolean
          nullable: true
          default: false
          example: true
          description: >
            Indicates if transcription redaction is enabled for inbound call
            recordings.

            Requires `transcriptionEnabled` to be true.
        deleteUnredactedTranscript:
          type: boolean
          nullable: true
          default: true
          example: true
          description: >
            Indicates if the unredacted transcript should be deleted after
            redaction.

            Requires `transcriptionRedactionEnabled` to be true.
      required:
        - recordingEnabled
    callIntelligenceSettings:
      title: Call Intelligence Settings
      description: Call Intelligence settings for a phone number.
      type: object
      properties:
        origination:
          $ref: '#/components/schemas/originationSettings'
      required:
        - origination
    callIntelligenceSettingsData:
      title: Call Intelligence Settings Data
      type: object
      properties:
        phoneNumber:
          type: string
          example: '+19191234567'
          description: The E.164-formatted phone number these settings apply to.
        origination:
          $ref: '#/components/schemas/originationSettings'
      required:
        - phoneNumber
        - origination
    callIntelligenceSettingsResponseSchema:
      title: Call Intelligence Settings Response
      description: >-
        Response envelope for individual TN Call Intelligence settings
        operations.
      type: object
      required:
        - links
        - data
        - errors
      properties:
        links:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/links'
        data:
          type: object
          nullable: true
          allOf:
            - $ref: '#/components/schemas/callIntelligenceSettingsData'
        errors:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/error'
      example:
        links:
          - href: >-
              https://api.bandwidth.com/v2/accounts/9999999/call-intelligence/phone-numbers/+19191234567
            rel: self
            method: GET
        data:
          phoneNumber: '+19191234567'
          origination:
            recordingEnabled: true
            recordingRedactionEnabled: true
            deleteUnredactedRecording: true
            transcriptionEnabled: true
            transcriptionRedactionEnabled: true
            deleteUnredactedTranscript: true
        errors: []
    bulkProvisionRequest:
      title: Bulk Provision Request
      description: Request body for a bulk Call Intelligence provisioning operation.
      type: object
      required:
        - action
        - phoneNumbers
        - origination
      properties:
        action:
          type: string
          enum:
            - PROVISION
          description: Provision Call Intelligence settings on the specified phone numbers.
          example: PROVISION
        phoneNumbers:
          type: array
          description: The list of E.164-formatted phone numbers to provision.
          items:
            type: string
          minItems: 1
        origination:
          $ref: '#/components/schemas/originationSettings'
      example:
        action: PROVISION
        phoneNumbers:
          - '+19191234567'
          - '+19197654321'
        origination:
          recordingEnabled: true
          recordingRedactionEnabled: false
          deleteUnredactedRecording: true
          transcriptionEnabled: false
          transcriptionRedactionEnabled: false
          deleteUnredactedTranscript: true
    bulkUnprovisionRequest:
      title: Bulk Unprovision Request
      description: Request body for a bulk Call Intelligence unprovisioning operation.
      type: object
      required:
        - action
        - phoneNumbers
      properties:
        action:
          type: string
          enum:
            - UNPROVISION
          description: >-
            Unprovision Call Intelligence settings from the specified phone
            numbers.
          example: UNPROVISION
        phoneNumbers:
          type: array
          description: The list of E.164-formatted phone numbers to unprovision.
          items:
            type: string
          minItems: 1
      example:
        action: UNPROVISION
        phoneNumbers:
          - '+19191234567'
          - '+19197654321'
    callIntelligenceSettingsListResponseSchema:
      title: List Call Intelligence Settings Response
      description: >-
        Paginated list of Call Intelligence settings across all provisioned
        phone numbers on the account.
      type: object
      required:
        - links
        - data
        - page
        - errors
      properties:
        links:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/links'
        data:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/callIntelligenceSettingsData'
        page:
          $ref: '#/components/schemas/page'
        errors:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/error'
      example:
        links:
          - href: >-
              https://api.bandwidth.com/v2/accounts/9999999/call-intelligence/phone-numbers?offset=0&limit=100
            rel: self
            method: GET
          - href: >-
              https://api.bandwidth.com/v2/accounts/9999999/call-intelligence/phone-numbers?limit=100
            rel: first
            method: GET
          - href: >-
              https://api.bandwidth.com/v2/accounts/9999999/call-intelligence/phone-numbers?offset=0&limit=100
            rel: last
            method: GET
        data:
          - phoneNumber: '+19191234567'
            origination:
              recordingEnabled: true
              recordingRedactionEnabled: true
              deleteUnredactedRecording: true
              transcriptionEnabled: true
              transcriptionRedactionEnabled: true
              deleteUnredactedTranscript: true
          - phoneNumber: '+19197654321'
            origination:
              recordingEnabled: true
              recordingRedactionEnabled: false
              deleteUnredactedRecording: true
              transcriptionEnabled: false
              transcriptionRedactionEnabled: false
              deleteUnredactedTranscript: true
        page:
          pageSize: 100
          totalElements: 2
          totalPages: 1
          pageNumber: 0
        errors: []
    bulkProvisionData:
      title: Bulk Provision Data
      type: object
      nullable: true
      properties:
        bulkId:
          type: string
          example: bulk-abc-123
          description: >-
            The unique identifier for this bulk provisioning request. Use this
            to poll for status.
        status:
          type: string
          enum:
            - PENDING
            - IN_PROGRESS
            - COMPLETE
            - PARTIAL_SUCCESS
            - FAILED
          example: PENDING
          description: The current status of the bulk provisioning request.
      required:
        - bulkId
        - status
    bulkProvisionResponseSchema:
      title: Bulk Provision Accepted Response
      description: Response envelope returned when a bulk provisioning request is accepted.
      type: object
      required:
        - links
        - data
        - errors
      properties:
        links:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/links'
        data:
          $ref: '#/components/schemas/bulkProvisionData'
        errors:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/error'
      example:
        links:
          - href: >-
              https://api.bandwidth.com/v2/accounts/9999999/call-intelligence/phone-numbers/bulk/bulk-abc-123
            rel: self
            method: GET
        data:
          bulkId: bulk-abc-123
          status: PENDING
        errors: []
    page:
      title: Page
      description: >-
        Pagination properties to facilitate the API client's navigation through
        the dataset.
      type: object
      properties:
        pageSize:
          type: number
          description: The number of resources on the current page.
          example: 100
        totalElements:
          type: number
          nullable: true
          description: The total number of elements in the response across all pages.
          example: 450
        totalPages:
          type: number
          nullable: true
          description: The total number of pages in the response.
          example: 5
        pageNumber:
          type: number
          description: The number of the current page.
          example: 0
      required:
        - pageSize
        - pageNumber
    bulkResultEntry:
      title: Bulk Result Entry
      type: object
      properties:
        phoneNumber:
          type: string
          example: '+19197654321'
          description: The phone number that was provisioned or unprovisioned.
        status:
          type: string
          enum:
            - SUCCESS
            - FAILED
          example: FAILED
          description: The result status for this phone number.
        description:
          type: string
          nullable: true
          example: Phone number not found on account.
          description: >-
            A description of why this phone number failed. Null if status is
            SUCCESS.
      required:
        - phoneNumber
        - status
    bulkStatusData:
      title: Bulk Status Data
      type: object
      nullable: true
      properties:
        bulkId:
          type: string
          example: bulk-abc-123
          description: The unique identifier for this bulk provisioning request.
        status:
          type: string
          enum:
            - PENDING
            - IN_PROGRESS
            - COMPLETE
            - PARTIAL_SUCCESS
            - FAILED
          example: COMPLETE
          description: The current status of the bulk provisioning request.
        action:
          type: string
          enum:
            - PROVISION
            - UNPROVISION
          example: PROVISION
          description: The action that was requested.
        origination:
          type: object
          nullable: true
          description: >-
            The Call Intelligence origination settings that were applied by this
            bulk provisioning request. Not included or null for UNPROVISION
            actions.
          allOf:
            - $ref: '#/components/schemas/originationSettings'
        results:
          type: array
          nullable: true
          description: >-
            The per-phone-number results of the bulk operation. Populated once
            processing has begun.
          items:
            $ref: '#/components/schemas/bulkResultEntry'
      required:
        - bulkId
        - status
        - action
        - results
    bulkStatusResponseSchema:
      title: Bulk Status Response
      description: Response envelope for a bulk provisioning status request.
      type: object
      required:
        - links
        - data
        - errors
        - page
      properties:
        links:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/links'
        data:
          $ref: '#/components/schemas/bulkStatusData'
        errors:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/error'
        page:
          $ref: '#/components/schemas/page'
      example:
        links:
          - href: >-
              https://api.bandwidth.com/v2/accounts/9999999/call-intelligence/phone-numbers/bulk/bulk-abc-123?offset=0&limit=100
            rel: self
            method: GET
          - href: >-
              https://api.bandwidth.com/v2/accounts/9999999/call-intelligence/phone-numbers/bulk/bulk-abc-123?limit=100
            rel: first
            method: GET
          - href: >-
              https://api.bandwidth.com/v2/accounts/9999999/call-intelligence/phone-numbers/bulk/bulk-abc-123?offset=0&limit=100
            rel: last
            method: GET
        data:
          bulkId: bulk-abc-123
          status: PARTIAL_SUCCESS
          action: PROVISION
          origination:
            recordingEnabled: true
            recordingRedactionEnabled: true
            deleteUnredactedRecording: true
            transcriptionEnabled: true
            transcriptionRedactionEnabled: true
            deleteUnredactedTranscript: true
          results:
            - phoneNumber: '+19191234567'
              status: SUCCESS
              description: null
            - phoneNumber: '+19197654321'
              status: FAILED
              description: Phone number not found on account.
        errors: []
        page:
          pageSize: 100
          totalElements: 2
          totalPages: 1
          pageNumber: 0
    error:
      title: Error
      type: object
      required:
        - type
        - description
      properties:
        id:
          type: string
          example: f47ac10b-58cc-4372-a567-0e02b2c3d479
          description: A unique identifier for the error.
        type:
          type: string
          example: resource-not-found
          description: The type of error.
        description:
          type: string
          example: The resource specified cannot be found.
          description: A description of the error.
        code:
          type: integer
          example: 50420
          description: The error code.
    errorResponse:
      title: Error Response
      type: object
      properties:
        links:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/links'
        data:
          type: object
          nullable: true
        errors:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/error'
      required:
        - links
        - data
        - errors
      example:
        links: []
        data: null
        errors:
          - id: '50420'
            type: resource-not-found
            description: The resource specified cannot be found.
            code: 50420
    links:
      title: Links
      type: object
      properties:
        href:
          type: string
          description: URI of the link.
          example: >-
            https://api.bandwidth.com/v2/accounts/9999999/call-intelligence/phone-numbers/+19191234567
        rel:
          type: string
          description: Specifies the relationship between this link and the resource.
          example: self
        method:
          type: string
          description: HTTP method to be used.
          example: GET
  responses:
    noContentResponse:
      description: No Content
    listCallIntelligenceSettingsResponse:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/callIntelligenceSettingsListResponseSchema'
    callIntelligenceSettingsResponse:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/callIntelligenceSettingsResponseSchema'
    callIntelligenceSettingsCreatedResponse:
      description: Created
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/callIntelligenceSettingsResponseSchema'
    bulkProvisionAcceptedResponse:
      description: Accepted
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/bulkProvisionResponseSchema'
    bulkStatusResponse:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/bulkStatusResponseSchema'
    badRequestResponse:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    unauthorizedResponse:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    forbiddenResponse:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    notFoundResponse:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    methodNotAllowedResponse:
      description: Method Not Allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    tooManyRequestsResponse:
      description: Too Many Requests
      headers:
        Retry-After:
          description: Number of seconds to wait before retrying the request.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    internalServerErrorResponse:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
  securitySchemes:
    Basic:
      type: http
      scheme: basic
      description: >-
        Basic authentication is a simple authentication scheme built into the
        HTTP protocol. To use it, send your HTTP requests with an Authorization
        header that contains the word Basic followed by a space and a
        base64-encoded string `username:password`.

        Example: `Authorization: Basic ZGVtbZpwQDU1dzByZA==`
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Bearer authentication (also called token authentication) is an HTTP
        authentication scheme that involves security tokens called bearer
        tokens. The client must send this token in the Authorization header when
        making requests to protected resources.

        Example: `Authorization: Bearer <token>`
security:
  - Basic: []
  - Bearer: []
tags:
  - name: Call Intelligence
