# Basic sales campaign — weekdays 09:00–17:00 New York
curl -X POST "https://app.talkover.ai/api/v1/campaigns" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Campaign Q1",
    "description": "Outbound sales campaign for Q1",
    "campaign_type": "sales",
    "agent_id": "agent-uuid-1",
    "start_date": "2024-01-01",
    "days_of_week": [1, 2, 3, 4, 5],
    "call_time_ranges": [
      {"start": "09:00", "end": "17:00"}
    ],
    "timezone": "America/New_York"
  }'

const response = await fetch('https://app.talkover.ai/api/v1/campaigns', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer talq_your_environment_token_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Sales Campaign Q1',
    description: 'Outbound sales campaign for Q1',
    campaign_type: 'sales',
    agent_id: 'agent-uuid-1',
    start_date: '2024-01-01',
    days_of_week: [1, 2, 3, 4, 5],
    call_time_ranges: [
      { start: '09:00', end: '17:00' }
    ],
    timezone: 'America/New_York'
  })
});

const result = await response.json();

import requests

url = "https://app.talkover.ai/api/v1/campaigns"
headers = {
    "Authorization": "Bearer talq_your_environment_token_here",
    "Content-Type": "application/json"
}
data = {
    "name": "Sales Campaign Q1",
    "description": "Outbound sales campaign for Q1",
    "campaign_type": "sales",
    "agent_id": "agent-uuid-1",
    "start_date": "2024-01-01",
    "days_of_week": [1, 2, 3, 4, 5],
    "call_time_ranges": [
        {"start": "09:00", "end": "17:00"}
    ],
    "timezone": "America/New_York"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

{
  "success": true,
  "data": {
    "id": "campaign-uuid-1",
    "name": "Sales Campaign Q1",
    "description": "Outbound sales campaign for Q1",
    "campaign_type": "sales",
    "status": "draft",
    "agent_id": "agent-uuid-1",
    "start_date": "2024-01-01",
    "end_date": null,
    "days_of_week": [1, 2, 3, 4, 5],
    "call_time_ranges": [
      {"start": "09:00", "end": "17:00"}
    ],
    "timezone": "America/New_York",
    "max_retries": 3,
    "retry_cooldown_hours": 24,
    "do_not_call_enabled": false,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

POST

api

campaigns

# Basic sales campaign — weekdays 09:00–17:00 New York
curl -X POST "https://app.talkover.ai/api/v1/campaigns" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Campaign Q1",
    "description": "Outbound sales campaign for Q1",
    "campaign_type": "sales",
    "agent_id": "agent-uuid-1",
    "start_date": "2024-01-01",
    "days_of_week": [1, 2, 3, 4, 5],
    "call_time_ranges": [
      {"start": "09:00", "end": "17:00"}
    ],
    "timezone": "America/New_York"
  }'

const response = await fetch('https://app.talkover.ai/api/v1/campaigns', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer talq_your_environment_token_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Sales Campaign Q1',
    description: 'Outbound sales campaign for Q1',
    campaign_type: 'sales',
    agent_id: 'agent-uuid-1',
    start_date: '2024-01-01',
    days_of_week: [1, 2, 3, 4, 5],
    call_time_ranges: [
      { start: '09:00', end: '17:00' }
    ],
    timezone: 'America/New_York'
  })
});

const result = await response.json();

import requests

url = "https://app.talkover.ai/api/v1/campaigns"
headers = {
    "Authorization": "Bearer talq_your_environment_token_here",
    "Content-Type": "application/json"
}
data = {
    "name": "Sales Campaign Q1",
    "description": "Outbound sales campaign for Q1",
    "campaign_type": "sales",
    "agent_id": "agent-uuid-1",
    "start_date": "2024-01-01",
    "days_of_week": [1, 2, 3, 4, 5],
    "call_time_ranges": [
        {"start": "09:00", "end": "17:00"}
    ],
    "timezone": "America/New_York"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

{
  "success": true,
  "data": {
    "id": "campaign-uuid-1",
    "name": "Sales Campaign Q1",
    "description": "Outbound sales campaign for Q1",
    "campaign_type": "sales",
    "status": "draft",
    "agent_id": "agent-uuid-1",
    "start_date": "2024-01-01",
    "end_date": null,
    "days_of_week": [1, 2, 3, 4, 5],
    "call_time_ranges": [
      {"start": "09:00", "end": "17:00"}
    ],
    "timezone": "America/New_York",
    "max_retries": 3,
    "retry_cooldown_hours": 24,
    "do_not_call_enabled": false,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

Create Campaign

Create a new campaign with scheduling, retry policy, cooldowns, and do-not-call rules. Campaigns are created in draft status — call Update Campaign Status with "status": "active" to start dispatching calls.

Endpoint

POST /api/v1/campaigns

Request headers

string

required

Bearer token for authentication. Format: Bearer talq_your_environment_token_here

string

required

Must be set to application/json

Request body

Identification

string

required

Campaign name. Max 255 characters.

string

Free-form description of the campaign.

string

required

Campaign category. Options: sales, follow_up, reminder, custom.

string

required

UUID of the agent assigned to the campaign. The agent must exist in your environment.

Schedule

string

required

Date the campaign becomes eligible to dispatch calls. Format: YYYY-MM-DD.

string

Optional end date. Must be after start_date. Format: YYYY-MM-DD.

array

required

Array of weekday numbers when calls can be placed. 1 = Monday, 7 = Sunday. At least one value required.

array

required

Time windows (per day) during which calls can be dispatched. Array of objects with start and end in HH:MM format (24h). At least one window required. Each window’s end must be after its start.Example: [{"start": "09:00", "end": "12:00"}, {"start": "14:00", "end": "17:00"}]

string

required

IANA timezone for call_time_ranges (e.g., America/New_York, America/Sao_Paulo, Europe/London). Max 50 characters.

Retry & Cooldown

integer

Initial delay (in seconds) before the first call attempt. Default: 0.

integer

Maximum retry attempts per contact. Range: 0–10. Default: 3.

integer

Hours to wait between retry attempts. Range: 1–168. Default: 24.

boolean

When true, the campaign automatically transitions to completed once all contacts have been processed.

boolean

When true, calls that completed but didn’t convert are retried after the cooldown.

boolean

When true, applies a cooldown to all contacts after the campaign completes (prevents immediate re-engagement by another campaign).

integer

Hours of cooldown applied to contacts after campaign completion. Range: 1–168. Default: 168.

Per-status cooldowns

These optional fields override retry_cooldown_hours for specific call outcomes. All in range 1–168 hours.

integer

Cooldown after a successful call.

integer

Cooldown after reaching voicemail.

integer

Cooldown after no-answer.

integer

Cooldown after busy signal.

integer

Cooldown after a failed call.

Do-Not-Call (DNC)

boolean

When true, contacts are checked against a DNC list before dispatching. Default: false.

string

Source of the DNC list. Options:

environment — DNC list shared across all campaigns in this environment
global — platform-wide DNC list
custom — campaign-specific list provided in do_not_call_custom_list

array

Array of phone numbers (E.164) blocked for this campaign. Used only when do_not_call_list_source is custom.

boolean

When true, contacts that match auto_dnc_trigger_statuses or auto_dnc_trigger_errors are automatically added to the DNC list.

array

Call statuses that trigger auto-add to DNC. Example: ["completed", "voicemail"].

array

Call errors that trigger auto-add to DNC. Example: ["invalid_number", "disconnected"].

Examples

# Basic sales campaign — weekdays 09:00–17:00 New York
curl -X POST "https://app.talkover.ai/api/v1/campaigns" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Campaign Q1",
    "description": "Outbound sales campaign for Q1",
    "campaign_type": "sales",
    "agent_id": "agent-uuid-1",
    "start_date": "2024-01-01",
    "days_of_week": [1, 2, 3, 4, 5],
    "call_time_ranges": [
      {"start": "09:00", "end": "17:00"}
    ],
    "timezone": "America/New_York"
  }'

const response = await fetch('https://app.talkover.ai/api/v1/campaigns', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer talq_your_environment_token_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Sales Campaign Q1',
    description: 'Outbound sales campaign for Q1',
    campaign_type: 'sales',
    agent_id: 'agent-uuid-1',
    start_date: '2024-01-01',
    days_of_week: [1, 2, 3, 4, 5],
    call_time_ranges: [
      { start: '09:00', end: '17:00' }
    ],
    timezone: 'America/New_York'
  })
});

const result = await response.json();

import requests

url = "https://app.talkover.ai/api/v1/campaigns"
headers = {
    "Authorization": "Bearer talq_your_environment_token_here",
    "Content-Type": "application/json"
}
data = {
    "name": "Sales Campaign Q1",
    "description": "Outbound sales campaign for Q1",
    "campaign_type": "sales",
    "agent_id": "agent-uuid-1",
    "start_date": "2024-01-01",
    "days_of_week": [1, 2, 3, 4, 5],
    "call_time_ranges": [
        {"start": "09:00", "end": "17:00"}
    ],
    "timezone": "America/New_York"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

# Campaign with split call windows + custom DNC + per-status cooldowns
curl -X POST "https://app.talkover.ai/api/v1/campaigns" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Follow-up Campaign",
    "campaign_type": "follow_up",
    "agent_id": "agent-uuid-2",
    "start_date": "2024-01-15",
    "end_date": "2024-03-31",
    "days_of_week": [1, 2, 3, 4, 5],
    "call_time_ranges": [
      {"start": "10:00", "end": "12:00"},
      {"start": "14:00", "end": "17:00"}
    ],
    "timezone": "America/Sao_Paulo",
    "max_retries": 5,
    "retry_cooldown_hours": 48,
    "success_cooldown_hours": 168,
    "voicemail_cooldown_hours": 24,
    "no_answer_cooldown_hours": 12,
    "busy_cooldown_hours": 6,
    "failed_cooldown_hours": 72,
    "do_not_call_enabled": true,
    "do_not_call_list_source": "custom",
    "do_not_call_custom_list": ["+15551234567", "+15559876543"],
    "auto_add_to_dnc_enabled": true,
    "auto_dnc_trigger_statuses": ["completed"],
    "auto_dnc_trigger_errors": ["invalid_number"]
  }'

Response

Success Response (201 Created)

{
  "success": true,
  "data": {
    "id": "campaign-uuid-1",
    "name": "Sales Campaign Q1",
    "description": "Outbound sales campaign for Q1",
    "campaign_type": "sales",
    "status": "draft",
    "agent_id": "agent-uuid-1",
    "start_date": "2024-01-01",
    "end_date": null,
    "days_of_week": [1, 2, 3, 4, 5],
    "call_time_ranges": [
      {"start": "09:00", "end": "17:00"}
    ],
    "timezone": "America/New_York",
    "max_retries": 3,
    "retry_cooldown_hours": 24,
    "do_not_call_enabled": false,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

Response fields

boolean

required

Indicates if the campaign was created successfully.

object

required

The created campaign object. New campaigns start in status: "draft". Use Update Campaign Status to activate.

Error responses

422 Validation Error

{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "agent_id": ["The selected agent id is invalid."],
    "call_time_ranges": ["The call time ranges field is required."],
    "call_time_ranges.0.end": ["The call time ranges.0.end must be a date after call time ranges.0.start."],
    "days_of_week.0": ["The days of week.0 must be between 1 and 7."]
  }
}

401 Unauthorized

{
  "message": "Missing Bearer Token"
}

403 Forbidden — Plan Limit Reached

{
  "success": false,
  "message": "Your plan does not allow creating more campaigns",
  "code": "CAMPAIGN_LIMIT_REACHED"
}

Notes

The campaign agent must already exist. Create it via Create Agent.
call_time_ranges replaces the older earliest_call_time/latest_call_time fields. Multiple windows let you skip lunch hours or split between morning and afternoon.
All *_cooldown_hours fields default to 24 if not provided. Use them to fine-tune retry behavior per call outcome.
Time windows are evaluated in the campaign’s timezone, not the caller’s local time.

Get Started

Concepts

API Reference

Guides

Create Campaign

Create Campaign

Endpoint

Request headers

Request body

Identification

Schedule

Retry & Cooldown

Per-status cooldowns

Do-Not-Call (DNC)

Examples

Response

Success Response (201 Created)

Response fields

Error responses

422 Validation Error

401 Unauthorized

403 Forbidden — Plan Limit Reached

Notes

​Create Campaign

​Endpoint

​Request headers

​Request body

​Identification

​Schedule

​Retry & Cooldown

​Per-status cooldowns

​Do-Not-Call (DNC)

​Examples

​Response

​Success Response (201 Created)

​Response fields

​Error responses

​422 Validation Error

​401 Unauthorized

​403 Forbidden — Plan Limit Reached

​Notes

​Related endpoints

Create Campaign

Endpoint

Request headers

Request body

Identification

Schedule

Retry & Cooldown

Per-status cooldowns

Do-Not-Call (DNC)

Examples

Response

Success Response (201 Created)

Response fields

Error responses

422 Validation Error

401 Unauthorized

403 Forbidden — Plan Limit Reached

Notes

Related endpoints