{
  "openapi": "3.0.1",
  "info": {
    "title": "Contact Center Campaigns API",
    "description": "Use the Campaign Management API to control the lifecycle of outbound campaigns and dynamically inject records for dialling from your own systems.\n\n## Prerequisites\nThe 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.\n\n## Authentication\nAll requests require two headers obtained from Admin Console and Configuration Manager:\n\n| Header | Description |\n|--------|-------------|\n| `x-api-key` | The **Key** value from your API app in Admin Console (`admin.8x8.com/api-access`) |\n| `X-8x8-Tenant` | The **Tenant Name** from **Home > Profile** in Configuration Manager |\n\n## Content Type\nAll requests must include the header `Content-Type: application/vnd.campaigns.v1+json`.\n\n## Customer Site\nThe `{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"
        }
      }
    }
  ],
  "tags": [
    {
      "name": "External Campaign API",
      "description": "External customer-facing endpoints for campaign management"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "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": {
    "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_`."
      }
    },
    "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.\nRecords are dialed in priority order (HIGH first).\n",
            "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"
      },
      "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)"
      },
      "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"
      },
      "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"
      },
      "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.\nRecords are dialed in priority order (HIGH first).\n",
            "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" }
      },
      "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
              }
            }
          }
        ]
      },
      "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"
      }
    }
  }
}