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

# Campaign YAML

> Define an entire campaign — goal, topics, contacts — in one file and launch it with a single command.

Instead of stitching together API calls, you can describe a campaign declaratively in a YAML file and create it with `ontora campaigns create -c campaign.yaml`.

## Example

```yaml theme={null}
name: Q2 facility-ops interviews
goal: Map current scheduling workflows and identify automation opportunities
description: |
  Talk to facility managers and shift leads about how they assign daily work.
channel: in_app_chat
duration_minutes: 30

interview_context_for_employee: |
  We're trying to understand how scheduling actually happens day-to-day —
  not the official process, but the real one.

success_criteria: |
  Each topic explored with at least 60% of contacts.

topics:
  - name: Daily scheduling
    goal: Understand how shifts are assigned each morning
    priority: high
    success_threshold: 0.7
    sub_topics:
      - Who decides assignments
      - What inputs they use
      - Where the friction is
    questions:
      - "Walk me through how this morning's shift assignment happened."
      - "What's the worst that's happened when scheduling went wrong?"

  - name: Tooling
    goal: Identify what tools facility managers actually use
    priority: medium
    success_threshold: 0.5

contacts:
  - { name: Sam Rivera,    email: sam@example.com,    department: Operations }
  - { name: Jess Thompson, email: jess@example.com,   department: Operations, seniority_level: senior }
```

Then:

```bash theme={null}
ontora campaigns create -c campaign.yaml           # creates in draft
ontora campaigns create -c campaign.yaml --start   # creates and immediately starts
```

The CLI prints the campaign id; if you skipped `--start`, launch with `ontora campaigns start <id>` when you're ready.

For larger contact lists, leave `contacts` out of the YAML and import them after creation:

```bash theme={null}
ontora contacts import <id> contacts.csv
```

## Field reference

### Top-level

| Field                            | Required | Description                                   |
| -------------------------------- | -------- | --------------------------------------------- |
| `name`                           | yes      | Display name                                  |
| `goal`                           | yes      | Research goal — drives agent behavior         |
| `description`                    | no       | Internal context                              |
| `channel`                        | yes      | `in_app_chat`, `voice`, `calendar`, etc.      |
| `duration_minutes`               | no       | Soft limit per conversation                   |
| `interview_context_for_employee` | no       | Shown to participants before the conversation |
| `success_criteria`               | no       | Free-form description used during synthesis   |
| `topics`                         | yes      | Array — see below                             |
| `contacts`                       | no       | Array — see below                             |

### Topic

| Field               | Required | Description                                                  |
| ------------------- | -------- | ------------------------------------------------------------ |
| `name`              | yes      | Topic title                                                  |
| `goal`              | yes      | What we want to learn                                        |
| `priority`          | no       | `high \| medium \| low`                                      |
| `success_threshold` | no       | 0.0–1.0; share of contacts that should cover this topic      |
| `sub_topics`        | no       | Array of strings                                             |
| `questions`         | no       | Array of starter questions (the agent improvises follow-ups) |

### Contact

```yaml theme={null}
- name: Sam Rivera
  email: sam@example.com
  department: Operations
  job_title: Shift Lead
  seniority_level: senior
```

For bulk lists, prefer `ontora contacts import <id> contacts.csv` after creating the campaign — see [Commands](/cli/commands#ontora-contacts). CSV columns: `name,email,phone,job_title,department,seniority`. Only `name` is required.