> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentcallback.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Run a campaign with the API

> Upload contacts, create and start a campaign, retrieve outcomes, and receive post-call webhooks.

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

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

<Steps>
  <Step title="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.

    ```csv theme={null}
    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.

    ```bash theme={null}
    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`.

    ```json theme={null}
    {
      "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:

    ```bash theme={null}
    curl --request GET "https://www.agentcallback.com/api/file-uploads" \
      --header "x-api-key: YOUR_API_KEY"
    ```
  </Step>

  <Step title="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.

    ```bash theme={null}
    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.

    <Note>
      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.
    </Note>

    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`.
  </Step>

  <Step title="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:

    ```json theme={null}
    {
      "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](/build-voice-agents/post-call-webhooks) for delivery details, trigger conditions, and the default payload.
  </Step>

  <Step title="Start the campaign">
    Starting a draft campaign queues eligible contacts. Calls run only during the configured working hours.

    ```bash theme={null}
    curl --request POST "https://www.agentcallback.com/api/campaigns/YOUR_CAMPAIGN_ID/start" \
      --header "x-api-key: YOUR_API_KEY"
    ```
  </Step>

  <Step title="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.

    ```bash theme={null}
    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:

    ```bash theme={null}
    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](/monitoring/call-logs).
  </Step>
</Steps>

## Next steps

* [Set up campaign retries](/deploy/campaigns/setup-retries) for unanswered calls.
* [Set up a campaign schedule](/deploy/campaigns/setup-schedule) to control starts and calling hours.
* [Review post-call webhook payloads](/build-voice-agents/post-call-webhooks) before connecting a production endpoint.