Run a campaign with the API

Use the AgentCallback API to run a CSV-backed outbound campaign from start to finish.

Before you begin

You need an API key, an outbound agent, and an active outbound phone number in your organization. The agent must already contain any variables that you map from the CSV. This guide uses these placeholders:

Placeholder	Value
`YOUR_API_KEY`	An API key from Dashboard > API Keys.
`YOUR_SCRIPT_ID`	The ID of your outbound agent.
`YOUR_FROM_PHONE_NUMBER`	An active outbound number in your organization, in E.164 format.
`YOUR_WEBHOOK_URL`	A public HTTPS endpoint you control.

Only upload contacts you are allowed to call. You are responsible for consent, local calling restrictions, and any applicable do-not-call requirements.

Prepare and upload the CSV

Your CSV needs a header row. The phone column and any mapped variable columns must use the same names you send when creating the campaign.

phone,first_name
+15551234567,Ada
+15557654321,Grace

Upload the file with multipart/form-data. The file field must be named file; CSV files can be up to 10 MB.

curl --request POST "https://www.agentcallback.com/api/file-uploads" \
  --header "x-api-key: YOUR_API_KEY" \
  --form "file=@/absolute/path/to/leads.csv;type=text/csv"

The response contains the ID you will use as file_upload_id.

{
  "success": true,
  "file_upload": {
    "id": "YOUR_FILE_UPLOAD_ID",
    "filename": "leads.csv",
    "total_rows": 2
  }
}

You can list the CSV files available to your organization at any time:

curl --request GET "https://www.agentcallback.com/api/file-uploads" \
  --header "x-api-key: YOUR_API_KEY"

Create a draft campaign

Create the campaign with the returned file_upload_id. AgentCallback imports the CSV rows into the campaign when it is created.The phone_number_column value must match the CSV phone header. Each key in script_variables must be the name of an agent variable, and its value must match the corresponding CSV header.

curl --request POST "https://www.agentcallback.com/api/campaigns" \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Outbound follow-up",
    "description": "Contacts imported from leads.csv",
    "script_id": "YOUR_SCRIPT_ID",
    "file_upload_id": "YOUR_FILE_UPLOAD_ID",
    "from_phone_number": "YOUR_FROM_PHONE_NUMBER",
    "routing_strategy": "single",
    "campaign_timezone": "America/Los_Angeles",
    "max_concurrent_calls": 1,
    "call_spacing_seconds": 180,
    "variable_mappings": {
      "phone_number_column": "phone",
      "script_variables": {
        "first_name": "first_name"
      }
    },
    "working_hours": {
      "weekly": {
        "monday": [{ "start": "09:00", "end": "17:00" }],
        "tuesday": [{ "start": "09:00", "end": "17:00" }],
        "wednesday": [{ "start": "09:00", "end": "17:00" }],
        "thursday": [{ "start": "09:00", "end": "17:00" }],
        "friday": [{ "start": "09:00", "end": "17:00" }]
      }
    }
  }'

The response includes campaign.id. Save it as YOUR_CAMPAIGN_ID for the remaining requests.

Omit scheduled_date and scheduled_time to create a draft. To create a scheduled campaign, provide both fields and optionally set scheduled_timezone_input. Do not send start_immediately; that field is not part of the API.

The working_hours object always uses the shape { weekly: { day: [{ start, end }] } }. Times use 24-hour HH:mm format. working_hours_timezone is optional; when omitted, working hours inherit campaign_timezone.

Configure the post-call webhook

Post-call webhooks belong to the agent, so configure the webhook before you start the campaign. It will receive call data for calls that use that agent.In the dashboard, open the agent used by the campaign, open Post-call Webhook, enable it, and set YOUR_WEBHOOK_URL as the destination. Choose POST unless your endpoint specifically requires GET.If you manage agents through the API, include this object in the complete PUT /api/scripts/YOUR_SCRIPT_ID agent configuration:

{
  "post_call_webhook": {
    "enabled": true,
    "url": "YOUR_WEBHOOK_URL",
    "method": "POST"
  }
}

Keep the agent’s other current fields in that PUT request. See Post-call webhooks for delivery details, trigger conditions, and the default payload.

Start the campaign

Starting a draft campaign queues eligible contacts. Calls run only during the configured working hours.

curl --request POST "https://www.agentcallback.com/api/campaigns/YOUR_CAMPAIGN_ID/start" \
  --header "x-api-key: YOUR_API_KEY"

Retrieve outcomes and export calls

Calls are asynchronous. Query the campaign’s calls after they begin completing. The response contains call status, phone number, summary, and transcript fields where available.

curl --request GET "https://www.agentcallback.com/api/campaigns/YOUR_CAMPAIGN_ID/calls?page=1&limit=30" \
  --header "x-api-key: YOUR_API_KEY"

To download the campaign’s calls as CSV:

curl --request GET "https://www.agentcallback.com/api/campaigns/YOUR_CAMPAIGN_ID/calls/export" \
  --header "x-api-key: YOUR_API_KEY" \
  --output campaign-calls.csv

You can also review the campaign and webhook delivery details in Call logs.

Next steps

Set up campaign retries for unanswered calls.
Set up a campaign schedule to control starts and calling hours.
Review post-call webhook payloads before connecting a production endpoint.

Platform

Build voice agents

Phone numbers

Voices

Deploy

Monitoring

Accounts and workspace

Before you begin

Next steps

​Before you begin

​Next steps

Before you begin

Next steps