# Request 1: Get campaign details
curl -X GET "https://app.talkover.ai/api/v1/campaigns/campaign-uuid-1" \
  -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,
    "enable_post_completion_cooldown": true,
    "post_completion_cooldown_hours": 168,
    "success_cooldown_hours": 168,
    "voicemail_cooldown_hours": 24,
    "no_answer_cooldown_hours": 24,
    "busy_cooldown_hours": 24,
    "failed_cooldown_hours": 24,
    "do_not_call_enabled": true,
    "do_not_call_list_source": "environment",
    "auto_add_to_dnc_enabled": true,
    "auto_dnc_trigger_statuses": ["completed", "voicemail"],
    "auto_dnc_trigger_errors": ["invalid_number", "disconnected"],
    "agent": {
      "id": "agent-uuid-1",
      "name": "Sales Agent",
      "label": "Sales Agent Label"
    },
    "calls": [
      {
        "id": "call-uuid-1",
        "to": "+1234567890",
        "status": "completed",
        "retries": 0,
        "created_at": "2024-01-01T00:00:00Z"
      },
      {
        "id": "call-uuid-2",
        "to": "+1987654321",
        "status": "failed",
        "retries": 1,
        "created_at": "2024-01-01T01:00:00Z"
      }
    ],
    "files": [
      {
        "id": "file-uuid-1",
        "original_filename": "contacts.csv",
        "processed_filename": "processed_contacts.csv",
        "status": "processed",
        "total_records": 1000,
        "processed_records": 950
      },
      {
        "id": "file-uuid-2",
        "original_filename": "leads.xlsx",
        "processed_filename": "processed_leads.csv",
        "status": "processing",
        "total_records": 500,
        "processed_records": 0
      }
    ],
    "stats": {
      "total_calls": 100,
      "completed_calls": 80,
      "failed_calls": 20,
      "success_rate": 80.0,
      "average_duration": 120
    },
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}

GET

api

campaigns

{campaign_id}

# Request 1: Get campaign details
curl -X GET "https://app.talkover.ai/api/v1/campaigns/campaign-uuid-1" \
  -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,
    "enable_post_completion_cooldown": true,
    "post_completion_cooldown_hours": 168,
    "success_cooldown_hours": 168,
    "voicemail_cooldown_hours": 24,
    "no_answer_cooldown_hours": 24,
    "busy_cooldown_hours": 24,
    "failed_cooldown_hours": 24,
    "do_not_call_enabled": true,
    "do_not_call_list_source": "environment",
    "auto_add_to_dnc_enabled": true,
    "auto_dnc_trigger_statuses": ["completed", "voicemail"],
    "auto_dnc_trigger_errors": ["invalid_number", "disconnected"],
    "agent": {
      "id": "agent-uuid-1",
      "name": "Sales Agent",
      "label": "Sales Agent Label"
    },
    "calls": [
      {
        "id": "call-uuid-1",
        "to": "+1234567890",
        "status": "completed",
        "retries": 0,
        "created_at": "2024-01-01T00:00:00Z"
      },
      {
        "id": "call-uuid-2",
        "to": "+1987654321",
        "status": "failed",
        "retries": 1,
        "created_at": "2024-01-01T01:00:00Z"
      }
    ],
    "files": [
      {
        "id": "file-uuid-1",
        "original_filename": "contacts.csv",
        "processed_filename": "processed_contacts.csv",
        "status": "processed",
        "total_records": 1000,
        "processed_records": 950
      },
      {
        "id": "file-uuid-2",
        "original_filename": "leads.xlsx",
        "processed_filename": "processed_leads.csv",
        "status": "processing",
        "total_records": 500,
        "processed_records": 0
      }
    ],
    "stats": {
      "total_calls": 100,
      "completed_calls": 80,
      "failed_calls": 20,
      "success_rate": 80.0,
      "average_duration": 120
    },
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}

Get Campaign

Retrieve detailed information about a specific campaign, including its configuration, associated calls, uploaded files, and performance statistics.

Endpoint

GET /api/v1/campaigns/{campaign_id}

Path Parameters

campaign

string

required

The unique identifier of the campaign. You can find this in your dashboard under Campaigns.

Request Headers

Authorization

string

required

Bearer token for authentication. Format: Bearer talq_your_environment_token_here

Example Requests

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

# Request 2: Get campaign with specific ID
curl -X GET "https://app.talkover.ai/api/v1/campaigns/550e8400-e29b-41d4-a716-446655440000" \
  -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,
    "enable_post_completion_cooldown": true,
    "post_completion_cooldown_hours": 168,
    "success_cooldown_hours": 168,
    "voicemail_cooldown_hours": 24,
    "no_answer_cooldown_hours": 24,
    "busy_cooldown_hours": 24,
    "failed_cooldown_hours": 24,
    "do_not_call_enabled": true,
    "do_not_call_list_source": "environment",
    "auto_add_to_dnc_enabled": true,
    "auto_dnc_trigger_statuses": ["completed", "voicemail"],
    "auto_dnc_trigger_errors": ["invalid_number", "disconnected"],
    "agent": {
      "id": "agent-uuid-1",
      "name": "Sales Agent",
      "label": "Sales Agent Label"
    },
    "calls": [
      {
        "id": "call-uuid-1",
        "to": "+1234567890",
        "status": "completed",
        "retries": 0,
        "created_at": "2024-01-01T00:00:00Z"
      },
      {
        "id": "call-uuid-2",
        "to": "+1987654321",
        "status": "failed",
        "retries": 1,
        "created_at": "2024-01-01T01:00:00Z"
      }
    ],
    "files": [
      {
        "id": "file-uuid-1",
        "original_filename": "contacts.csv",
        "processed_filename": "processed_contacts.csv",
        "status": "processed",
        "total_records": 1000,
        "processed_records": 950
      },
      {
        "id": "file-uuid-2",
        "original_filename": "leads.xlsx",
        "processed_filename": "processed_leads.csv",
        "status": "processing",
        "total_records": 500,
        "processed_records": 0
      }
    ],
    "stats": {
      "total_calls": 100,
      "completed_calls": 80,
      "failed_calls": 20,
      "success_rate": 80.0,
      "average_duration": 120
    },
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}

Response Fields

success

boolean

required

Indicates if the operation was successful.

data

object

required

Campaign details object.

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.

enable_post_completion_cooldown

boolean

required

Whether post-completion cooldown is enabled.

post_completion_cooldown_hours

integer

required

Hours to wait after campaign completion.

success_cooldown_hours

integer

required

Hours to wait after successful calls.

voicemail_cooldown_hours

integer

required

Hours to wait after voicemail calls.

no_answer_cooldown_hours

integer

required

Hours to wait after no-answer calls.

busy_cooldown_hours

integer

required

Hours to wait after busy calls.

failed_cooldown_hours

integer

required

Hours to wait after failed calls.

do_not_call_enabled

boolean

required

Whether do-not-call list checking is enabled.

do_not_call_list_source

string

required

Source of do-not-call list. Options: environment, campaign.

auto_add_to_dnc_enabled

boolean

required

Whether to automatically add numbers to do-not-call list.

auto_dnc_trigger_statuses

array

required

Call statuses that trigger auto-add to DNC.

auto_dnc_trigger_errors

array

required

Call errors that trigger auto-add to DNC.

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.

calls

array

required

Array of calls associated with this campaign.

Show Call Object

string

required

Unique identifier for the call.

string

required

Destination phone number.

status

string

required

Status of the call.

retries

integer

required

Number of retry attempts made.

created_at

string

required

ISO 8601 timestamp when the call was created.

files

array

required

Array of files uploaded to this campaign.

Show File Object

string

required

Unique identifier for the file.

original_filename

string

required

Original filename as uploaded.

processed_filename

string

required

Processed filename after conversion.

status

string

required

Processing status. Options: uploading, processing, processed, failed.

total_records

integer

required

Total number of records in the file.

processed_records

integer

required

Number of records successfully processed.

stats

object

required

Campaign performance 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.

average_duration

integer

required

Average call duration in seconds.

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.

Error Responses

404 Not Found

{
  "success": false,
  "message": "Campaign not found"
}

401 Unauthorized

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

500 Server Error

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

Error Codes

Code	Description	HTTP Status
`CAMPAIGN_NOT_FOUND`	Specified campaign does not exist	404
`INVALID_TOKEN`	Authentication token is invalid or missing	401
`SERVER_ERROR`	Internal server error occurred	500

Important Notes

Comprehensive data. This endpoint returns complete campaign information including calls, files, and statistics.

Real-time statistics. Campaign statistics are updated in real-time as calls are processed.

File processing status. Monitor file uploads and processing status through the files array.

Call history. View all calls associated with the campaign, including retry attempts.

Best Practices

Monitor file processing - Check file status to ensure contacts are properly loaded
Track call progress - Use the calls array to monitor individual call status
Review statistics - Analyze success rates and average duration for optimization
Handle errors - Implement proper error handling for missing campaigns
Cache wisely - Campaign data can be cached but should be refreshed periodically

List Campaigns: GET /api/v1/campaigns
Create Campaign: POST /api/v1/campaigns
Update Campaign: PUT /api/v1/campaigns/{campaign_id}
Update Campaign Status: PATCH /api/v1/campaigns/{campaign_id}/status
Delete Campaign: DELETE /api/v1/campaigns/{campaign_id}
Make Campaign Call: POST /api/v1/campaigns/{campaign_id}/call

Create Campaign Update Campaign

Get Started

Concepts

API Reference

Guides

Get Campaign

Get Campaign

Endpoint

Path Parameters

Request Headers

Example Requests

Response

Success Response (200 OK)

Response Fields

Error Responses

404 Not Found

401 Unauthorized

500 Server Error

Error Codes

Important Notes

Best Practices

Get Started

Concepts

API Reference

Guides

Documentation Index

​Get Campaign

​Endpoint

​Path Parameters

​Request Headers

​Example Requests

​Response

​Success Response (200 OK)

​Response Fields

​Error Responses

​404 Not Found

​401 Unauthorized

​500 Server Error

​Error Codes

​Important Notes

​Best Practices

​Related Endpoints

Get Campaign

Endpoint

Path Parameters

Request Headers

Example Requests

Response

Success Response (200 OK)

Response Fields

Error Responses

404 Not Found

401 Unauthorized

500 Server Error

Error Codes

Important Notes

Best Practices

Related Endpoints