Outbound Campaigns is currently in Beta. The API and functionality may change.
Endpoints#
List All Campaigns#
Retrieve all outbound campaigns in your organization.Request#
Response#
{
"campaigns": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Q1 Sales Outreach",
"status": "scheduled",
"agent_id": "17a0cb75-fa09-4bdd-9a44-92a70d829c88",
"system_message_template": "You are calling {{name}} from {{company}}. Their role is {{role}}.",
"schedule_start_time": "09:00:00",
"schedule_end_time": "17:00:00",
"timezone": "Europe/Amsterdam",
"total_leads": 150,
"completed_leads": 45,
"created_at": "2026-01-07T10:00:00.000Z",
"updated_at": "2026-01-07T14:30:00.000Z"
}
]
}
Create a Campaign#
Create a new outbound calling campaign.Request Body#
| Field | Type | Required | Description |
|---|
name | string | Yes | Campaign display name |
agent_id | UUID | Yes | Agent to use for calls |
system_message_template | string | No | Template with {{variable}} placeholders |
schedule_start_time | string | No | Daily start time (HH:MM:SS), default: 09:00:00 |
schedule_end_time | string | No | Daily end time (HH:MM:SS), default: 17:00:00 |
timezone | string | No | IANA timezone, default: Europe/Amsterdam |
status | string | No | draft, scheduled, paused, completed |
Example Request#
Response (201 Created)#
{
"campaign": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Q1 Sales Outreach",
"status": "draft",
...
}
}
Get a Campaign#
Retrieve a specific campaign by ID.Parameters#
| Name | In | Type | Description |
|---|
id | path | UUID | Campaign UUID |
Request#
Response#
{
"campaign": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Q1 Sales Outreach",
"status": "scheduled",
"agent_id": "17a0cb75-fa09-4bdd-9a44-92a70d829c88",
"system_message_template": "You are calling {{name}} from {{company}}.",
"schedule_start_time": "09:00:00",
"schedule_end_time": "17:00:00",
"timezone": "Europe/Amsterdam",
"total_leads": 150,
"completed_leads": 45,
"current_call_id": null,
"last_lead_processed_at": "2026-01-07T14:25:00.000Z",
"created_at": "2026-01-07T10:00:00.000Z",
"updated_at": "2026-01-07T14:30:00.000Z"
}
}
Update a Campaign#
Update campaign settings or status.Parameters#
| Name | In | Type | Description |
|---|
id | path | UUID | Campaign UUID |
Request Body#
All fields are optional. Only include fields you want to update.Set status to scheduled to start calling leads. Set to paused to stop.
Example Request#
Response#
{
"campaign": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "scheduled",
...
}
}
Delete a Campaign#
Delete a campaign and all its leads.This action is irreversible. All leads and call history associated with the campaign will be deleted.
Parameters#
| Name | In | Type | Description |
|---|
id | path | UUID | Campaign UUID |
Request#
Response#
List Campaign Leads#
Retrieve all leads in a campaign.GET /campaigns/{id}/leads
Parameters#
| Name | In | Type | Description |
|---|
id | path | UUID | Campaign UUID |
Request#
Response#
{
"leads": [
{
"id": "lead-uuid-1",
"phone_number": "+31612345678",
"status": "completed",
"variables": {
"name": "Jan de Vries",
"company": "TechCorp",
"role": "CTO"
},
"call_id": "call-uuid-123",
"attempts": 1,
"last_attempt_at": "2026-01-07T10:15:00.000Z",
"created_at": "2026-01-07T10:00:00.000Z"
},
{
"id": "lead-uuid-2",
"phone_number": "+31687654321",
"status": "pending",
"variables": {
"name": "Maria Jansen",
"company": "DataFlow",
"role": "CEO"
},
"call_id": null,
"attempts": 0,
"last_attempt_at": null,
"created_at": "2026-01-07T10:00:00.000Z"
}
]
}
Lead Status Values#
| Status | Description |
|---|
pending | Lead has not been called yet |
calling | Call is currently in progress |
completed | Call completed successfully |
failed | Call failed (will not be retried) |
no_answer | No answer after maximum attempts |
Add a Lead#
Add a new lead to a campaign.POST /campaigns/{id}/leads
Parameters#
| Name | In | Type | Description |
|---|
id | path | UUID | Campaign UUID |
Request Body#
| Field | Type | Required | Description |
|---|
phone_number | string | Yes | Phone number in E.164 format |
variables | object | No | Key-value pairs for template interpolation |
Example Request#
Response (201 Created)#
{
"lead": {
"id": "lead-uuid-new",
"phone_number": "+31612345678",
"status": "pending",
"variables": {
"name": "Jan de Vries",
"company": "TechCorp",
"role": "CTO",
"notes": "Interested in enterprise plan"
},
"attempts": 0,
"created_at": "2026-01-07T15:00:00.000Z"
}
}
Remove a Lead#
Remove a lead from a campaign.DELETE /campaigns/{id}/leads/{leadId}
Parameters#
| Name | In | Type | Description |
|---|
id | path | UUID | Campaign UUID |
leadId | path | UUID | Lead UUID |
Request#
Response#
Variable Interpolation#
The system_message_template supports variable interpolation using {{variable}} syntax. Variables are matched against the variables object of each lead.Example#
You are calling {{name}} from {{company}}.
Their role is {{role}}.
Additional context: {{notes}}
{
"name": "Jan de Vries",
"company": "TechCorp",
"role": "CTO",
"notes": "Interested in enterprise plan"
}
You are calling Jan de Vries from TechCorp.
Their role is CTO.
Additional context: Interested in enterprise plan
Variables that are not found in the lead's variables object will remain as {{variable}} in the final message.
Calls API - View call details and transcripts 