8x8 External Campaign API

openapi: 3.2.0
info:
  title: Contact Center Campaigns External Campaign External Campaign API
  description: 'Use the Campaign Management API to control the lifecycle of outbound campaigns and dynamically inject records for dialling from your own systems.


    ## Prerequisites

    The campaign must be configured as a **Dynamic Campaign** in Configuration Manager before records can be added via the API. However, campaign state can be changed via this API for both regular and dynamic campaigns.


    ## Authentication

    All requests require two headers obtained from Admin Console and Configuration Manager:


    | Header | Description |

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

    | `x-api-key` | The **Key** value from your API app in Admin Console (`admin.8x8.com/api-access`) |

    | `X-8x8-Tenant` | The **Tenant Name** from **Home > Profile** in Configuration Manager |


    ## Content Type

    All requests must include the header `Content-Type: application/vnd.campaigns.v1+json`.


    ## Customer Site

    The `{customer-site}` path parameter is your site identifier'
  version: 1.0.0
  contact:
    name: 8x8 Support
    url: https://support.8x8.com
  termsOfService: https://www.8x8.com/terms-and-conditions
servers:
- url: https://api.8x8.com/cc/{customer-site}/campaigns/v1
  description: Production
  variables:
    customer-site:
      default: US1
      description: Your Contact Center site identifier
security:
- ApiKeyAuth: []
tags:
- name: External Campaign API
  description: External customer-facing endpoints for campaign management
paths:
  /{campaignId}/records:
    post:
      tags:
      - External Campaign API
      summary: Add records to campaign
      description: Add one or more records (1-100) to a dynamic campaign. Records are validated, CRM data is queried, and phone numbers are checked against DNC lists. Operation is atomic - all records succeed or all fail.
      operationId: addRecords
      parameters:
      - name: x-api-key
        in: header
        description: Admin Console API Key with the **Contact Center Campaigns** API Product attached. Always starts with `eght_`.
        required: true
        schema:
          type: string
      - name: X-8x8-Tenant
        in: header
        description: Tenant identifier
        required: true
        schema:
          type: string
      - name: campaignId
        in: path
        description: Campaign UUID
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/vnd.campaigns.v1+json:
            schema:
              $ref: '#/components/schemas/AddRecordsRequest'
        required: true
      responses:
        '400':
          description: Invalid request, validation failure, or duplicate CRM IDs
          content:
            application/vnd.campaigns.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '201':
          description: Records successfully added
          content:
            application/vnd.campaigns.v1+json:
              schema:
                $ref: '#/components/schemas/AddRecordsResponse'
        '404':
          description: Campaign not found
          content:
            application/vnd.campaigns.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '500':
          description: Internal server error
          content:
            application/vnd.campaigns.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
  /{campaignId}:
    patch:
      tags:
      - External Campaign API
      summary: Modify campaign state
      description: Change campaign state. State transitions are validated and must follow allowed state machine rules.
      operationId: modifyCampaign
      parameters:
      - name: x-api-key
        in: header
        description: Admin Console API Key with the **Contact Center Campaigns** API Product attached. Always starts with `eght_`.
        required: true
        schema:
          type: string
      - name: X-8x8-Tenant
        in: header
        description: Tenant identifier
        required: true
        schema:
          type: string
      - name: campaignId
        in: path
        description: Campaign UUID
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/vnd.campaigns.v1+json:
            schema:
              description: Campaign modification request
              oneOf:
              - $ref: '#/components/schemas/ModifyCampaignRequest'
              - $ref: '#/components/schemas/StartCampaignRequest'
        required: true
      responses:
        '400':
          description: Invalid request or illegal state transition
          content:
            application/vnd.campaigns.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: Campaign not found
          content:
            application/vnd.campaigns.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '500':
          description: Internal server error
          content:
            application/vnd.campaigns.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '200':
          description: Campaign successfully modified
          content:
            application/vnd.campaigns.v1+json:
              schema:
                $ref: '#/components/schemas/Campaign'
components:
  schemas:
    AddRecordRequest:
      maxLength: 100
      minLength: 1
      required:
      - crmRecordId
      type: object
      properties:
        crmRecordId:
          maxLength: 32
          minLength: 1
          type: string
          description: CRM record identifier - must be unique within campaign
          example: CRM-12345
        scheduleAt:
          type: string
          description: Schedule record attempt (optional). Records are ordered by the earliest scheduleAt value first, triggering only at (or after) the scheduleAt time.
          format: date-time
          example: '2024-01-16T10:00:00Z'
        priority:
          type: string
          description: 'Dialing priority: HIGH, MEDIUM, LOW.

            Records are dialed in priority order (HIGH first).

            '
          example: HIGH
          enum:
          - HIGH
          - MEDIUM
          - LOW
        rank:
          type: number
          description: Ranking within priority group (optional, auto-assigned if not provided)
          format: double
          example: 1.5
      description: Request to add a single record to a campaign
    FieldError:
      type: object
      properties:
        field:
          type: string
          description: Field name
          example: crmRecordId
        code:
          type: string
          description: Error code
          example: NotBlank
        message:
          type: string
          description: Error message
          example: must not be blank
      description: Validation error for a specific field
    StartCampaignRequest:
      type: object
      description: Request to start a campaign, optionally triggering a build-then-start sequence
      allOf:
      - $ref: '#/components/schemas/ModifyCampaignRequest'
      - type: object
        properties:
          buildOnStart:
            type: boolean
            description: Build the campaign before starting. Set to true to trigger an automatic build-then-start sequence without a separate BUILD call. Overrides the Campaign'sbuild on start value.
            example: false
    ErrorMessage:
      type: object
      properties:
        title:
          type: string
          description: Short, human-readable summary of the problem
          example: Validation failed
        status:
          type: integer
          description: HTTP status code
          format: int32
          example: 400
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence
          example: 'Campaign already contains record for Id: CRM-12345'
        instance:
          type: string
          description: URI reference identifying the specific occurrence
        time:
          type: string
          description: Timestamp when error occurred
          format: date-time
          example: '2024-01-15T10:30:00Z'
        errors:
          type: array
          description: Field-level validation errors (if applicable)
          items:
            $ref: '#/components/schemas/FieldError'
      description: RFC 9457 Problem JSON error response
    Campaign:
      type: object
      properties:
        id:
          type: string
          description: Campaign unique identifier
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174000
        tenantId:
          type: string
          description: Tenant identifier
          example: tenant-123
        integrationType:
          type: string
          description: Integration type
          example: contactual
        startTime:
          type: string
          description: Scheduled start time
          format: date-time
          example: '2024-01-15T10:00:00Z'
        endTime:
          type: string
          description: Scheduled end time
          format: date-time
          example: '2024-01-15T18:00:00Z'
        state:
          type: string
          description: Campaign state
          example: RUNNING
          enum:
          - CREATED
          - BUILDING
          - READY
          - PENDING
          - STARTING
          - RUNNING
          - PAUSED
          - COMPLETE
          - BUILD_ERROR
          - RUN_ERROR
          - DELETED
        displayStatus:
          type: string
          description: Display status for UI
          example: ACTIVE
          enum:
          - NEW
          - BUILDING
          - BUILD_FAILED
          - READY_TO_RUN
          - SCHEDULED
          - RUNNING
          - PAUSED
          - PURGED
          - ERROR
          - ERROR_PURGED
          - COMPLETED
          - STOPPED
          - DISABLED
        recordCount:
          type: integer
          description: Total number of records
          format: int64
          example: 1500
        recordCounts:
          type: array
          description: Breakdown of record counts by state and result
          items:
            $ref: '#/components/schemas/RecordCount'
        lastBuildTime:
          type: string
          description: Last time campaign records were built
          format: date-time
          example: '2024-01-15T09:55:00Z'
        lastPurgedTime:
          type: string
          description: Last time campaign was purged
          format: date-time
          example: '2024-01-14T23:00:00Z'
        startedTime:
          type: string
          description: Time campaign actually started
          format: date-time
          example: '2024-01-15T10:00:05Z'
        completedTime:
          type: string
          description: Time campaign completed
          format: date-time
          example: '2024-01-15T17:45:00Z'
      description: Campaign representation with state, timing, and record statistics
    RecordCount:
      type: object
      properties:
        type:
          type: string
          description: Record type
          example: DYNAMIC
          enum:
          - CRM_QUERY
          - DYNAMIC
        state:
          type: string
          description: Record state
          example: READY
          enum:
          - PENDING
          - REQUESTED
          - QUEUED
          - CANCEL_REQUESTED
          - AGENT_ACCEPTED
          - COMPLETE
          - REJECTED
          - DELETED
          - ERROR
        result:
          type: string
          description: Record processing result
          example: COMPLETED
          enum:
          - SUCCESS
          - NO_VALID_NUMBER
          - SCHEDULE_COMPLETE
          - INTERACTION_FAILED
          - MAX_ATTEMPTS_REACHED
          - INTERACTION_SKIPPED
          - CALLBACK_SCHEDULED
        count:
          type: integer
          description: Count of records
          format: int64
          example: 45
      description: Record count by type, state, and result
    AddRecordsRequest:
      required:
      - records
      type: object
      properties:
        records:
          maxItems: 100
          minItems: 1
          type: array
          description: List of records to add - minimum 1, maximum 100
          items:
            $ref: '#/components/schemas/AddRecordRequest'
      description: Records to add (1-100 records)
    AddRecordsResponse:
      type: object
      properties:
        records:
          type: array
          description: List of records that were successfully added
          items:
            $ref: '#/components/schemas/Record'
      description: Response containing successfully added records
    Record:
      type: object
      properties:
        id:
          type: string
          description: Record unique identifier
          format: uuid
          example: 789e4567-e89b-12d3-a456-426614174000
        type:
          type: string
          description: Record type
          example: DYNAMIC
          enum:
          - CRM_QUERY
          - DYNAMIC
        crmRecordId:
          maxLength: 32
          type: string
          description: CRM record identifier
          example: CRM-12345
        priority:
          type: string
          description: 'Dialing priority: HIGH, MEDIUM, LOW.

            Records are dialed in priority order (HIGH first).

            '
          example: HIGH
          enum:
          - HIGH
          - MEDIUM
          - LOW
        rank:
          type: number
          description: Ranking within priority group
          format: double
          example: 1.5
        nextAttemptAfter:
          type: string
          description: Next scheduled attempt time
          format: date-time
          example: '2024-01-15T11:30:00Z'
        retryCount:
          type: integer
          description: Number of retry attempts
          format: int32
          example: 2
        state:
          type: string
          description: Record state
          example: READY
          enum:
          - PENDING
          - REQUESTED
          - QUEUED
          - CANCEL_REQUESTED
          - AGENT_ACCEPTED
          - COMPLETE
          - REJECTED
          - DELETED
          - ERROR
        stateReason:
          type: string
          description: Reason for current state
          example: Scheduled for retry
        result:
          type: string
          description: Record processing result
          example: COMPLETED
          enum:
          - SUCCESS
          - NO_VALID_NUMBER
          - SCHEDULE_COMPLETE
          - INTERACTION_FAILED
          - MAX_ATTEMPTS_REACHED
          - INTERACTION_SKIPPED
          - CALLBACK_SCHEDULED
      description: Campaign record representing a single contact to be dialed
    ModifyCampaignRequest:
      type: object
      properties:
        action:
          type: string
          description: Campaign action
          example: BUILD
          enum:
          - BUILD
          - RESET
          - START
          - PAUSE
          - RESUME
          - RETRY
          - CANCEL
          - PURGE
          - BUILD
          - RESET
          - START
          - PAUSE
          - RESUME
          - RETRY
          - CANCEL
          - PURGE
        enabled:
          type: boolean
          description: Enable or disable the campaign, leaving in the current state if not provided
          example: false
      description: Request to modify campaign state or properties
      discriminator:
        propertyName: action
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Admin Console API Key with the **Contact Center Campaigns** API Product attached to the app. The key value is the **Key** field from your app at [admin.8x8.com/api-access](https://admin.8x8.com/api-access) and always starts with `eght_`.