# Request 1: Get all campaigns
curl -X GET "https://app.talkover.ai/api/v1/campaigns" \
-H "Authorization: Bearer talq_your_environment_token_here"
// Request 1: Get all campaigns
const response = await fetch('https://app.talkover.ai/api/v1/campaigns', {
method: 'GET',
headers: {
'Authorization': 'Bearer talq_your_environment_token_here'
}
});
const result = await response.json();
console.log(result);
{
"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
}
}
Calls & Campaigns
List Campaigns
Retrieve a list of all campaigns with filtering and pagination options
GET
/
api
/
v1
/
campaigns
# Request 1: Get all campaigns
curl -X GET "https://app.talkover.ai/api/v1/campaigns" \
-H "Authorization: Bearer talq_your_environment_token_here"
// Request 1: Get all campaigns
const response = await fetch('https://app.talkover.ai/api/v1/campaigns', {
method: 'GET',
headers: {
'Authorization': 'Bearer talq_your_environment_token_here'
}
});
const result = await response.json();
console.log(result);
{
"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
string
required
Bearer token for authentication. Format:
Bearer talq_your_environment_token_hereQuery parameters
string
Filter by campaign status. Options:
draft, active, paused, completed, cancelledstring
Filter by campaign type. Options:
sales, follow_up, reminder, customstring
Filter by agent ID
string
Filter campaigns from date (YYYY-MM-DD)
string
Filter campaigns to date (YYYY-MM-DD)
string
Search in campaign name or description
integer
Number of items per page (default: 20, max: 100)
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 1: Get all campaigns
const response = await fetch('https://app.talkover.ai/api/v1/campaigns', {
method: 'GET',
headers: {
'Authorization': 'Bearer talq_your_environment_token_here'
}
});
const result = await response.json();
console.log(result);
# 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 2: Get active sales campaigns
const response = await fetch('https://app.talkover.ai/api/v1/campaigns?status=active&campaign_type=sales&per_page=50', {
method: 'GET',
headers: {
'Authorization': 'Bearer talq_your_environment_token_here'
}
});
const result = await response.json();
console.log(result);
# 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"
// Request 3: Search for specific campaign
const response = await fetch('https://app.talkover.ai/api/v1/campaigns?search=Sales Campaign&agent_id=agent-uuid-1', {
method: 'GET',
headers: {
'Authorization': 'Bearer talq_your_environment_token_here'
}
});
const result = await response.json();
console.log(result);
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
boolean
required
Indicates if the operation was successful.
array
required
Array of campaign objects.
Show Campaign Object
Show Campaign Object
string
required
Unique identifier for the campaign.
string
required
Name of the campaign.
string
Description of the campaign.
string
required
Current status of the campaign. Options:
draft, active, paused, completed, cancelled.string
required
Type of campaign. Options:
sales, follow_up, reminder, custom.string
required
Campaign start date (YYYY-MM-DD).
array
required
Array of days when calls can be made (1=Monday, 7=Sunday).
string
required
Earliest time to make calls (HH:MM:SS).
string
required
Latest time to make calls (HH:MM:SS).
string
required
Timezone for call scheduling.
string
required
UUID of the agent assigned to the campaign.
integer
required
Initial delay before making calls (seconds).
integer
required
Maximum number of retry attempts.
integer
required
Hours to wait between retry attempts.
object
required
object
required
string
required
ISO 8601 timestamp when the campaign was created.
string
required
ISO 8601 timestamp when the campaign was last updated.
object
required
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.
Related endpoints
- 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
Was this page helpful?