> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anyreach.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Campaigns overview
> Dial lists of contacts with a voice agent, on a schedule, at scale.
A campaign is an outbound dialing job that calls a list of contacts with a voice agent. Campaigns run over the telephone channel only — there are no email or SMS campaigns. You create a campaign, point it at a reusable configuration, load contacts, and the dialer places calls within the configuration's calling windows, retrying failed numbers according to its policy.
## The model
Four objects make up a campaign.
| Object | What it is |
| ------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Configuration | An org-level, reusable bundle of calling windows, retry policy, and the default agent. A campaign references exactly one. |
| Campaign | An outbound dialing job. References a configuration and holds contacts. Has a status and a priority. |
| Contact | A person to call, with one or more phone numbers, on a campaign (or no campaign, for ad-hoc calls). |
| Attempt | One call placed to a contact. Each attempt is linked to the resulting conversation. |
Dialing a contact creates an attempt. The attempt carries the `phone_number` that was dialed and a `conversation_id` linking it to the conversation the call produced, so every call is traceable back to its contact and campaign.
```
Configuration ──▶ Campaign ──▶ Contact ──▶ Attempt ──▶ Conversation
(reusable) (the job) (who) (one call) (the transcript)
```
A configuration is reusable across many campaigns. Define your calling windows and retry policy once, then create campaigns that share them. See [Configurations](/campaigns/configurations).
## Lifecycle
A campaign is always in one of three statuses.
| Status | Meaning | Set by |
| -------- | --------------------------------------------------------------- | ---------------------------------------------- |
| `active` | The dialer may place calls to this campaign's contacts. | `POST /campaign/campaigns/{campaign_id}/start` |
| `paused` | Calling is suspended. Contacts and configuration are untouched. | `POST /campaign/campaigns/{campaign_id}/pause` |
| `closed` | Permanently stopped. A closed campaign cannot be restarted. | `POST /campaign/campaigns/{campaign_id}/close` |
Newly created campaigns start in `active`. The lifecycle endpoints use conditional updates: start only takes effect if the campaign is not already `closed`, pause only if it is currently `active`, and close only if it is not already `closed`. A call that does not match these conditions returns `400`.
Campaign state changes are plain database writes — no workflow signals are involved. The dialer polls the database and picks up status changes within about a second, so pausing a campaign halts new calls almost immediately.
```
create ──▶ active ◀──pause──▶ paused
│ │
└──────close───────┴──▶ closed (terminal)
```
## Addressing campaigns and contacts
Every campaign and contact has a UUID `id`. You can also set an `external_id` — a stable identifier from your own system — and use it in place of the UUID. Endpoints that take a `{campaign_id}` resolve it as a UUID first and fall back to matching `external_id`; contact endpoints resolve `external_id` within the campaign. Use this to address records by your own keys without storing Anyreach UUIDs.
## Priority
Each campaign has a `priority` (integer, default `1`, range `0`–`999999`). When the dialer picks the next contacts to call, it orders eligible contacts by campaign priority descending — higher priority is dialed first — then prefers fresh contacts over retries, then oldest first.
Contacts that are not attached to any campaign are dialed at an effective priority of `1000000`, intentionally above the maximum campaign priority of `999999`. Ad-hoc calls jump ahead of campaign traffic.
## The default campaign
To place ad-hoc calls without creating a campaign, add contacts under the sentinel `campaign_id` of `default`. These contacts belong to no campaign — they are always eligible (no calling-window or active-status check) and dial at the elevated default priority described above. Because there is no configuration behind them, their phone numbers must already be valid E.164. Use this for one-off or programmatic calls; use a real campaign when you need scheduling, retries, and reporting.
## Agent override precedence
A configuration supplies the default agent, but you can override it per campaign or per contact. When the dialer resolves which agent to call with, it takes the first value that is set, in this order:
```
contact.agent_id ▶ campaign.agent_id ▶ configuration.agent_id
(most specific) (default)
```
The same precedence applies to the agent version and the caller-ID number. A per-contact agent wins over a per-campaign agent, which wins over the configuration default. If a contact ends up with no agent and no inline agent config, the dialer marks it as an error rather than placing the call.
## Next steps
Define reusable calling windows, retry policy, and the default agent.
Load contacts, set per-contact overrides, and schedule calls.
How the dialer picks contacts, respects windows, and retries.