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

# Campaign agents API

> Create and manage reusable Campaign Manager webhook configurations.

An agent is a reusable webhook configuration shared by multiple campaigns. It defines what Vobiz calls when a contact answers and, optionally, when the call ends.

<ParamField path="account_id" type="string" required>
  Your Vobiz account ID. Use the same value in `X-Auth-ID`.
</ParamField>

<ParamField header="X-Auth-ID" type="string" required>
  Your Vobiz account ID, for example `MA_XXXXXXXX`.
</ParamField>

<Note>
  A launch takes a frozen agent snapshot. Editing an agent does not change campaigns that are already `running` or `queued`. The next launch uses the updated values.
</Note>

## Endpoints

| Method   | Path                                                      | Description                |
| -------- | --------------------------------------------------------- | -------------------------- |
| `POST`   | `/api/v1/account/{account_id}/campaign/agents`            | Create an agent.           |
| `GET`    | `/api/v1/account/{account_id}/campaign/agents`            | List non-archived agents.  |
| `GET`    | `/api/v1/account/{account_id}/campaign/agents/{agent_id}` | Retrieve an agent.         |
| `PUT`    | `/api/v1/account/{account_id}/campaign/agents/{agent_id}` | Partially update an agent. |
| `DELETE` | `/api/v1/account/{account_id}/campaign/agents/{agent_id}` | Soft-delete an agent.      |

## Create an agent

| Field            | Required | Description                                               |
| ---------------- | -------- | --------------------------------------------------------- |
| `name`           | Yes      | Unique per account. Maximum 100 characters.               |
| `answer_url`     | Yes      | HTTPS URL called when the contact answers.                |
| `answer_method`  | No       | `GET` or `POST`. Defaults to `POST`.                      |
| `hangup_url`     | No       | URL called when the call ends.                            |
| `hangup_method`  | No       | `GET` or `POST`. Defaults to `POST`.                      |
| `static_headers` | No       | Array of `{ key, value }` SIP headers sent on every call. |

```bash cURL theme={null}
curl -X POST \
  "https://campaign.vobiz.ai/api/v1/account/{account_id}/campaign/agents" \
  -H "X-Auth-ID: {account_id}" \
  -H "X-Auth-Token: {auth_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Appointment Reminder Agent",
    "answer_url": "https://example.com/answer",
    "answer_method": "POST",
    "hangup_url": "https://example.com/hangup",
    "hangup_method": "POST",
    "static_headers": [
      { "key": "X-Campaign-Type", "value": "reminder" },
      { "key": "X-Version", "value": "1" }
    ]
  }'
```

A successful request returns `201`. Save the response `id` as `agent_id` when you create a campaign.

## List agents

Use `limit` and `offset` for pagination. The default page size is `20`.

```json 200 OK theme={null}
{
  "objects": [],
  "total": 5,
  "limit": 20,
  "offset": 0
}
```

## Update and delete

`PUT` is partial: only supplied fields change. `DELETE` archives the agent instead of hard-deleting its data.

Deleting returns `409` when the agent has a `running`, `queued`, or `paused` campaign. Finish, cancel, or archive the dependent campaigns first.