# Request 1: Get all campaigns
curl -X GET "https://app.talkover.ai/api/v1/campaigns" \
  -H "Authorization: Bearer talq_your_environment_token_here"

{
  "success": true,
  "data": [
    {
      "id": "campaign-uuid-1",
      "name": "Sales Campaign",
      "description": "Outbound sales campaign for Q1",
      "status": "active",
      "campaign_type": "sales",
      "start_date": "2024-01-01",
      "days_of_week": [1, 2, 3, 4, 5],
      "earliest_call_time": "09:00:00",
      "latest_call_time": "17:00:00",
      "timezone": "America/New_York",
      "agent_id": "agent-uuid-1",
      "initial_call_delay": 0,
      "max_retries": 3,
      "retry_cooldown_hours": 24,
      "agent": {
        "id": "agent-uuid-1",
        "name": "Sales Agent",
        "label": "Sales Agent Label"
      },
      "stats": {
        "total_calls": 100,
        "completed_calls": 80,
        "failed_calls": 20,
        "success_rate": 80.0
      },
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    },
    {
      "id": "campaign-uuid-2",
      "name": "Follow-up Campaign",
      "description": "Follow-up calls for existing customers",
      "status": "paused",
      "campaign_type": "follow_up",
      "start_date": "2024-01-15",
      "days_of_week": [2, 3, 4],
      "earliest_call_time": "10:00:00",
      "latest_call_time": "16:00:00",
      "timezone": "America/New_York",
      "agent_id": "agent-uuid-2",
      "initial_call_delay": 0,
      "max_retries": 2,
      "retry_cooldown_hours": 48,
      "agent": {
        "id": "agent-uuid-2",
        "name": "Support Agent",
        "label": "Support Agent Label"
      },
      "stats": {
        "total_calls": 50,
        "completed_calls": 35,
        "failed_calls": 15,
        "success_rate": 70.0
      },
      "created_at": "2024-01-15T00:00:00Z",
      "updated_at": "2024-01-15T00:00:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 20,
    "total": 100,
    "from": 1,
    "to": 20
  }
}

GET

api

campaigns

# Request 1: Get all campaigns
curl -X GET "https://app.talkover.ai/api/v1/campaigns" \
  -H "Authorization: Bearer talq_your_environment_token_here"

{
  "success": true,
  "data": [
    {
      "id": "campaign-uuid-1",
      "name": "Sales Campaign",
      "description": "Outbound sales campaign for Q1",
      "status": "active",
      "campaign_type": "sales",
      "start_date": "2024-01-01",
      "days_of_week": [1, 2, 3, 4, 5],
      "earliest_call_time": "09:00:00",
      "latest_call_time": "17:00:00",
      "timezone": "America/New_York",
      "agent_id": "agent-uuid-1",
      "initial_call_delay": 0,
      "max_retries": 3,
      "retry_cooldown_hours": 24,
      "agent": {
        "id": "agent-uuid-1",
        "name": "Sales Agent",
        "label": "Sales Agent Label"
      },
      "stats": {
        "total_calls": 100,
        "completed_calls": 80,
        "failed_calls": 20,
        "success_rate": 80.0
      },
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    },
    {
      "id": "campaign-uuid-2",
      "name": "Follow-up Campaign",
      "description": "Follow-up calls for existing customers",
      "status": "paused",
      "campaign_type": "follow_up",
      "start_date": "2024-01-15",
      "days_of_week": [2, 3, 4],
      "earliest_call_time": "10:00:00",
      "latest_call_time": "16:00:00",
      "timezone": "America/New_York",
      "agent_id": "agent-uuid-2",
      "initial_call_delay": 0,
      "max_retries": 2,
      "retry_cooldown_hours": 48,
      "agent": {
        "id": "agent-uuid-2",
        "name": "Support Agent",
        "label": "Support Agent Label"
      },
      "stats": {
        "total_calls": 50,
        "completed_calls": 35,
        "failed_calls": 15,
        "success_rate": 70.0
      },
      "created_at": "2024-01-15T00:00:00Z",
      "updated_at": "2024-01-15T00:00:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 20,
    "total": 100,
    "from": 1,
    "to": 20
  }
}

List Campaigns

Retrieve a list of all campaigns for the authenticated environment with various filtering options and pagination support.

Endpoint

GET /api/v1/campaigns

Request Headers

Authorization

string

required

Bearer token for authentication. Format: Bearer talq_your_environment_token_here

Query Parameters

status

string

Filter by campaign status. Options: draft, active, paused, completed, cancelled

campaign_type

string

Filter by campaign type. Options: sales, follow_up, reminder, custom

agent_id

string

Filter by agent ID

date_from

string

Filter campaigns from date (YYYY-MM-DD)

date_to

string

Filter campaigns to date (YYYY-MM-DD)

string

Search in campaign name or description

per_page

integer

Number of items per page (default: 20, max: 100)

page

integer

Page number (default: 1)

Example Requests

# Request 1: Get all campaigns
curl -X GET "https://app.talkover.ai/api/v1/campaigns" \
  -H "Authorization: Bearer talq_your_environment_token_here"

# Request 2: Get active sales campaigns
curl -X GET "https://app.talkover.ai/api/v1/campaigns?status=active&campaign_type=sales&per_page=50" \
  -H "Authorization: Bearer talq_your_environment_token_here"

# Request 3: Search for specific campaign
curl -X GET "https://app.talkover.ai/api/v1/campaigns?search=Sales Campaign&agent_id=agent-uuid-1" \
  -H "Authorization: Bearer talq_your_environment_token_here"

Response

Success Response (200 OK)

{
  "success": true,
  "data": [
    {
      "id": "campaign-uuid-1",
      "name": "Sales Campaign",
      "description": "Outbound sales campaign for Q1",
      "status": "active",
      "campaign_type": "sales",
      "start_date": "2024-01-01",
      "days_of_week": [1, 2, 3, 4, 5],
      "earliest_call_time": "09:00:00",
      "latest_call_time": "17:00:00",
      "timezone": "America/New_York",
      "agent_id": "agent-uuid-1",
      "initial_call_delay": 0,
      "max_retries": 3,
      "retry_cooldown_hours": 24,
      "agent": {
        "id": "agent-uuid-1",
        "name": "Sales Agent",
        "label": "Sales Agent Label"
      },
      "stats": {
        "total_calls": 100,
        "completed_calls": 80,
        "failed_calls": 20,
        "success_rate": 80.0
      },
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    },
    {
      "id": "campaign-uuid-2",
      "name": "Follow-up Campaign",
      "description": "Follow-up calls for existing customers",
      "status": "paused",
      "campaign_type": "follow_up",
      "start_date": "2024-01-15",
      "days_of_week": [2, 3, 4],
      "earliest_call_time": "10:00:00",
      "latest_call_time": "16:00:00",
      "timezone": "America/New_York",
      "agent_id": "agent-uuid-2",
      "initial_call_delay": 0,
      "max_retries": 2,
      "retry_cooldown_hours": 48,
      "agent": {
        "id": "agent-uuid-2",
        "name": "Support Agent",
        "label": "Support Agent Label"
      },
      "stats": {
        "total_calls": 50,
        "completed_calls": 35,
        "failed_calls": 15,
        "success_rate": 70.0
      },
      "created_at": "2024-01-15T00:00:00Z",
      "updated_at": "2024-01-15T00:00:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 20,
    "total": 100,
    "from": 1,
    "to": 20
  }
}

Response Fields

success

boolean

required

Indicates if the operation was successful.

data

array

required

Array of campaign objects.

Show Campaign Object

string

required

Unique identifier for the campaign.

name

string

required

Name of the campaign.

description

string

Description of the campaign.

status

string

required

Current status of the campaign. Options: draft, active, paused, completed, cancelled.

campaign_type

string

required

Type of campaign. Options: sales, follow_up, reminder, custom.

start_date

string

required

Campaign start date (YYYY-MM-DD).

days_of_week

array

required

Array of days when calls can be made (1=Monday, 7=Sunday).

earliest_call_time

string

required

Earliest time to make calls (HH:MM:SS).

latest_call_time

string

required

Latest time to make calls (HH:MM:SS).

timezone

string

required

Timezone for call scheduling.

agent_id

string

required

UUID of the agent assigned to the campaign.

initial_call_delay

integer

required

Initial delay before making calls (seconds).

max_retries

integer

required

Maximum number of retry attempts.

retry_cooldown_hours

integer

required

Hours to wait between retry attempts.

agent

object

required

Agent information assigned to the campaign.

Show Agent Object

string

required

Unique identifier for the agent.

name

string

required

Name of the agent.

label

string

required

Display label for the agent.

stats

object

required

Campaign statistics.

Show Stats Object

total_calls

integer

required

Total number of calls in the campaign.

completed_calls

integer

required

Number of successfully completed calls.

failed_calls

integer

required

Number of failed calls.

success_rate

number

required

Success rate percentage.

created_at

string

required

ISO 8601 timestamp when the campaign was created.

updated_at

string

required

ISO 8601 timestamp when the campaign was last updated.

pagination

object

required

Pagination metadata.

Show Pagination Object

Error Responses

401 Unauthorized

{
  "success": false,
  "message": "Unauthorized"
}

422 Validation Error

{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "status": [
      "The selected status is invalid."
    ],
    "campaign_type": [
      "The selected campaign type is invalid."
    ],
    "date_from": [
      "The date from must be a valid date."
    ]
  }
}

500 Server Error

{
  "success": false,
  "message": "Internal server error."
}

Error Codes

Code	Description	HTTP Status
`INVALID_TOKEN`	Authentication token is invalid or missing	401
`VALIDATION_ERROR`	Query parameter validation failed	422
`SERVER_ERROR`	Internal server error occurred	500

Important Notes

Pagination support. All list endpoints support pagination with page and per_page parameters.

Date filtering. Use date_from and date_to to filter campaigns by date range.

Search functionality. The search parameter searches in campaign names and descriptions.

Statistics included. Each campaign includes real-time statistics about call performance.

Best Practices

Use pagination - Always use pagination for large datasets
Filter by status - Use status filters to find active, paused, or completed campaigns
Monitor performance - Check campaign statistics to track success rates
Search efficiently - Use the search parameter to find specific campaigns quickly
Handle errors - Implement proper error handling for authentication and validation failures

Create Campaign: POST /api/v1/campaigns
Get Campaign: GET /api/v1/campaigns/{campaign_id}
Update Campaign: PUT /api/v1/campaigns/{campaign_id}
List Calls: GET /api/v1/calls

Get Agent Calls Create Campaign

Get Started

Concepts

API Reference

Guides

List Campaigns

List Campaigns

Endpoint

Request Headers

Query Parameters

Example Requests

Response

Success Response (200 OK)

Response Fields

Error Responses

401 Unauthorized

422 Validation Error

500 Server Error

Error Codes

Important Notes

Best Practices

Get Started

Concepts

API Reference

Guides

Documentation Index

​List Campaigns

​Endpoint

​Request Headers

​Query Parameters

​Example Requests

​Response

​Success Response (200 OK)

​Response Fields

​Error Responses

​401 Unauthorized

​422 Validation Error

​500 Server Error

​Error Codes

​Important Notes

​Best Practices

​Related Endpoints

List Campaigns

Endpoint

Request Headers

Query Parameters

Example Requests

Response

Success Response (200 OK)

Response Fields

Error Responses

401 Unauthorized

422 Validation Error

500 Server Error

Error Codes

Important Notes

Best Practices

Related Endpoints