Campaigns

Campaigns dial every contact in an audience using a selected voice flow.

The Campaign Object

{
  "id": "camp_def456",
  "name": "Mumbai Outreach - March 2026",
  "status": "IN_PROGRESS",
  "flowId": "flow_xyz789",
  "audienceId": "aud_abc123",
  "callsPerMinute": 10,
  "maxConcurrentCalls": 5,
  "maxRetries": 3,
  "retryDelayMinutes": 5,
  "callTimeoutMinutes": 5,
  "scheduledAt": null,
  "timezone": null,
  "organizationId": "org_1",
  "createdAt": "2026-03-10T09:00:00.000Z",
  "startedAt": "2026-03-10T09:05:00.000Z",
  "completedAt": null
}

Campaign Statuses

Status	Description
`DRAFT`	Created but not started
`SCHEDULED`	Waiting to start at `scheduledAt` time
`IN_PROGRESS`	Actively dialing contacts
`PAUSED`	Temporarily halted, can be resumed
`COMPLETED`	All contacts called
`CANCELLED`	Permanently stopped

List Campaigns

GET /v1/campaigns

Query Parameters:

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 20, max: 100)
`status`	string	Filter by status (e.g., `IN_PROGRESS`)
`search`	string	Search by campaign name

Get a Campaign

GET /v1/campaigns/:id

Create a Campaign

POST /v1/campaigns

Request Body:

Field	Type	Required	Description
`name`	string	Yes	Campaign name
`flowId`	string	Yes	ID of the voice flow to use
`audienceId`	string	Yes	ID of the audience to call
`callsPerMinute`	integer	No	Default: `10`
`maxConcurrentCalls`	integer	No	Default: `5`
`maxRetries`	integer	No	Default: `3`
`retryDelayMinutes`	integer	No	Default: `5`
`callTimeoutMinutes`	integer	No	Default: `5`
`scheduledAt`	string (ISO 8601)	No	Future start time
`timezone`	string	No	Required if `scheduledAt` is set (e.g., `Asia/Kolkata`)

Example:

{
  "name": "Mumbai Outreach - March 2026",
  "flowId": "flow_xyz789",
  "audienceId": "aud_abc123",
  "callsPerMinute": 10,
  "maxConcurrentCalls": 5,
  "maxRetries": 2,
  "scheduledAt": "2026-03-15T09:00:00Z",
  "timezone": "Asia/Kolkata"
}

Response: 201 Created with the Campaign object in DRAFT status.

Start a Campaign

POST /v1/campaigns/:id/start

Transitions the campaign from DRAFT or SCHEDULED to IN_PROGRESS.

OliAI checks your organization's quota before starting. If insufficient minutes remain, the request returns 402 Payment Required.

Response: 200 OK with updated Campaign object.

Pause a Campaign

POST /v1/campaigns/:id/pause

Stops new calls from being initiated. Calls in progress continue to completion.

Response: 200 OK with { "status": "PAUSED" }.

Resume a Campaign

POST /v1/campaigns/:id/resume

Continues a paused campaign from where it left off.

Response: 200 OK with { "status": "IN_PROGRESS" }.

Cancel a Campaign

POST /v1/campaigns/:id/cancel

Permanently stops the campaign. This cannot be undone.

Response: 200 OK with { "status": "CANCELLED" }.

Get Campaign Progress

GET /v1/campaigns/:id/progress

Response:

{
  "status": "IN_PROGRESS",
  "total": 250,
  "pending": 180,
  "queued": 5,
  "inProgress": 5,
  "completed": 55,
  "failed": 5,
  "skipped": 0,
  "percentComplete": 24
}

Get Campaign Calls

GET /v1/campaigns/:id/calls

Returns the individual call records for every contact in the campaign.

Query Parameters: page, limit

Response:

{
  "data": [
    {
      "callSid": "CA...",
      "contactId": "clxxx123",
      "contactName": "Priya Sharma",
      "phoneNumber": "+919876543210",
      "status": "COMPLETED",
      "duration": 87,
      "attempts": 1,
      "startedAt": "2026-03-10T09:07:00.000Z",
      "completedAt": "2026-03-10T09:08:27.000Z"
    }
  ],
  "total": 250,
  "page": 1,
  "limit": 20
}

Update a Campaign

PATCH /v1/campaigns/:id

⚠️

Campaigns can only be updated while in DRAFT status.

Request Body: Any subset of campaign creation fields.

Audiences Voice Flows