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

# Configurations

> Reusable calling windows, timezones, retry policy, and the agent to dial with.

A configuration is an org-level, reusable bundle that a campaign points at. It defines when contacts may be called (calling windows per timezone), how aggressively to retry, how to normalize uploaded phone numbers, and which agent version does the dialing. Create a configuration once and reuse it across many campaigns.

A configuration has three parts:

* **Schedule** — when calls are allowed, by timezone.
* **Dialing policy** — retry limit and the default country code for normalizing numbers.
* **Agent** — which agent (and version) to dial with.

## Schedule

The schedule controls which timezones are inside their calling window at a given moment. Calls are only placed to contacts whose timezone is currently in a window.

| Field                 | Type                         | Default            | Description                                                                                          |
| --------------------- | ---------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------- |
| `default_timezone`    | string (IANA)                | `America/New_York` | Fallback timezone for contacts that do not carry one. Must be a valid IANA identifier.               |
| `default_windows`     | `TimeWindow[]`               | `[]`               | Calling windows used for regular contacts and all retries. An empty list means no calls are allowed. |
| `overrides`           | `ScheduleOverride[]`         | `[]`               | Per-timezone window lists that replace `default_windows` for the listed timezones.                   |
| `scheduled_windows`   | `TimeWindow[]` \| null       | `null`             | Windows used only for first-time scheduled contacts. When `null`, falls back to `default_windows`.   |
| `scheduled_overrides` | `ScheduleOverride[]` \| null | `null`             | Per-timezone windows for first-time scheduled contacts. When `null`, falls back to `overrides`.      |

### TimeWindow

A `TimeWindow` is a set of weekdays plus a daily start and end time.

| Field   | Type      | Description                                                     |
| ------- | --------- | --------------------------------------------------------------- |
| `days`  | string\[] | One or more of `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun`. |
| `start` | string    | Start time in 24-hour `HH:MM` (hour 0-23, minute 0-59).         |
| `end`   | string    | End time in 24-hour `HH:MM`. Must differ from `start`.          |

If `start` is earlier than `end`, the window is a normal same-day range (for example `09:00`-`17:00`). If `start` is later than `end`, the window crosses midnight (for example `22:30`-`03:30`), and the early-morning portion is attributed to the previous day's `days` entry.

```json theme={null}
{
  "days": ["mon", "tue", "wed", "thu", "fri"],
  "start": "09:00",
  "end": "17:00"
}
```

<Warning>
  If `default_windows` is empty and no override matches a contact's timezone, no calls are placed to that contact. Set at least one window before launching a campaign.
</Warning>

### ScheduleOverride

A `ScheduleOverride` attaches a list of windows to one or more timezones. For any contact in a listed timezone, these windows replace `default_windows` entirely.

| Field       | Type           | Description                                         |
| ----------- | -------------- | --------------------------------------------------- |
| `timezones` | string\[]      | IANA timezone identifiers this override applies to. |
| `windows`   | `TimeWindow[]` | Windows used for the listed timezones.              |

```json theme={null}
{
  "timezones": ["America/Los_Angeles", "America/Vancouver"],
  "windows": [
    { "days": ["mon", "tue", "wed", "thu", "fri"], "start": "10:00", "end": "18:00" }
  ]
}
```

### Regular vs scheduled windows

There are two parallel sets of windows. Use scheduled windows when you want first-time scheduled contacts to be dialed on a different schedule than everyone else.

| Window set                                  | Applies to                         | Falls back to                               |
| ------------------------------------------- | ---------------------------------- | ------------------------------------------- |
| `default_windows` / `overrides`             | Regular contacts and all retries   | (none)                                      |
| `scheduled_windows` / `scheduled_overrides` | First-time scheduled contacts only | `default_windows` / `overrides` when `null` |

To list every valid IANA timezone identifier accepted by these fields, call:

```bash theme={null}
curl https://api.anyreach.ai/campaign/timezones \
  -H "Authorization: Bearer <token>" \
  -H "X-Anyreach-Org: <organization_id>"
```

## Dialing policy

| Field                           | Type    | Default | Constraints                | Description                                                                |
| ------------------------------- | ------- | ------- | -------------------------- | -------------------------------------------------------------------------- |
| `max_attempts_per_phone_number` | integer | `2`     | Minimum `1`                | How many times a single phone number may be dialed before it is exhausted. |
| `default_country_code`          | string  | `+1`    | `+` followed by 1-4 digits | Country code applied when normalizing uploaded numbers to E.164.           |

When contacts are uploaded against a campaign, numbers without an explicit country code are parsed using `default_country_code` and formatted to E.164 (for example, `+44`). Numbers that cannot be parsed are reported as invalid. See [Contacts](/campaigns/contacts) for upload behavior and [Dialing and retries](/campaigns/dialing-and-retries) for how attempts are spent.

## Agent

| Field      | Type            | Default  | Description                                                                             |
| ---------- | --------------- | -------- | --------------------------------------------------------------------------------------- |
| `agent_id` | UUID            | required | The agent that dials contacts in campaigns using this configuration.                    |
| `version`  | integer \| null | `null`   | A specific published agent version. When omitted, the latest published version is used. |

## Default configuration

A configuration can be marked as the organization's default with `is_default`. Only one default may exist per organization.

<Note>
  Creating or updating a configuration with `is_default: true` while a default already exists returns `409 Conflict`. Un-default or delete the existing default first.
</Note>

## Endpoints

All endpoints require the `campaigns:read` scope to read and `campaigns:manage` to create, update, or delete.

| Method   | Path                                   | Description                                                    |
| -------- | -------------------------------------- | -------------------------------------------------------------- |
| `POST`   | `/campaign/configurations`             | Create a configuration.                                        |
| `GET`    | `/campaign/configurations`             | List all configurations for the organization.                  |
| `GET`    | `/campaign/configurations/{config_id}` | Get one configuration.                                         |
| `PATCH`  | `/campaign/configurations/{config_id}` | Update a configuration. Changes propagate to active campaigns. |
| `DELETE` | `/campaign/configurations/{config_id}` | Delete a configuration.                                        |
| `GET`    | `/campaign/timezones`                  | List all valid IANA timezone identifiers.                      |

<Warning>
  Deleting a configuration that is referenced by one or more campaigns returns `409 Conflict`. Reassign or delete those campaigns first.
</Warning>

### Create a configuration

```bash theme={null}
curl -X POST https://api.anyreach.ai/campaign/configurations \
  -H "Authorization: Bearer <token>" \
  -H "X-Anyreach-Org: <organization_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "US business hours",
    "is_default": true,
    "default_timezone": "America/New_York",
    "default_windows": [
      { "days": ["mon", "tue", "wed", "thu", "fri"], "start": "09:00", "end": "17:00" }
    ],
    "max_attempts_per_phone_number": 2,
    "default_country_code": "+1",
    "agent_id": "00000000-0000-0000-0000-000000000000"
  }'
```

## Related

<CardGroup cols={2}>
  <Card title="Contacts" icon="users" href="/campaigns/contacts">
    Upload contacts and how numbers are normalized to E.164.
  </Card>

  <Card title="Dialing and retries" icon="phone" href="/campaigns/dialing-and-retries">
    How attempts and calling windows govern when calls go out.
  </Card>
</CardGroup>