Contact Center Campaigns API
8x8 Contact Center Campaigns API for creating campaigns and managing campaign records for outbound dialing.
OpenAPI Specification
{
"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"
}
}
}
}