Launch a campaign

This guide walks through creating a campaign, adding topics and contacts, and launching it programmatically. Use it as a template.

Prerequisites

A full access workspace API key (read + write) — launching sends real invitations. See Authentication.
Your workspace ID (API keys are workspace-scoped; the ID is shown alongside the key in Developer → API Keys).
A list of contacts (name + email at minimum).

How launching works

Creating a campaign is three calls: create the campaign shell, add topics as question sets, add contacts. POST /start then validates everything and sends the invitations on the campaign’s channel — in_app_chat (email with a personal interview link), slack (Slack DM), or teams (Microsoft Teams chat). Participants self-schedule. Two scheduling knobs worth knowing:

Scheduled send — pass start_immediately: false with a future timeframe_start and the invitations are held until the campaign opens (date-only starts send at 08:00 in the campaign’s timezone). The detail endpoint reports the exact instant as invitations_scheduled_for.
Soft deadline — timeframe_end is communicated to participants as the response deadline but never blocks late responses.

End-to-end script

import os, httpx

API_KEY = os.environ["ONTORA_API_KEY"]
WORKSPACE_ID = os.environ["ONTORA_WORKSPACE_ID"]
client = httpx.Client(
    base_url="https://api.ontora.com",
    headers={"X-API-Key": API_KEY},
    timeout=30.0,
)

# 1. Create the campaign shell
campaign = client.post("/v1/interviews", json={
    "workspace_id": WORKSPACE_ID,
    "name": "Q2 facility-ops interviews",
    "goal": "Map current scheduling workflows and identify automation opportunities",
    "channel": "in_app_chat",
    "default_language": "en",
    # Optional: schedule the send instead of emailing at launch
    # "start_immediately": False,
    # "timeframe_start": "2026-08-03",
    # "timeframe_end": "2026-08-14",
    # "timezone": "Europe/Berlin",
}).raise_for_status().json()

interview_id = campaign["id"]
print(f"Created campaign {interview_id}")

# 2. Add topics as question sets
client.post(f"/v1/interviews/{interview_id}/question-sets", json={
    "name": "Daily scheduling",
    "description": "Understand how shifts are assigned",
    "sort_order": 0,
    "topic_metadata": {"priority": "required", "sub_topics": ["Who decides", "Inputs used"]},
    "questions": [
        {"question_text": "Walk me through how this morning's shift assignment happened.",
         "is_required": True},
        {"question_text": "Rank these steps by how much time they cost you.",
         "question_type": "ranking",
         "component_config": {"items": [
             {"id": "intake", "label": "Intake"},
             {"id": "approval", "label": "Approval"},
         ]}},
    ],
}).raise_for_status()

# 3. Add contacts
client.post(f"/v1/interviews/{interview_id}/contacts/bulk", json={
    "contacts": [
        {"name": "Sam Rivera",    "email": "sam@example.com",  "department": "Operations"},
        {"name": "Jess Thompson", "email": "jess@example.com", "department": "Operations"},
    ],
}).raise_for_status()

# 4. Start the campaign — sends (or schedules) the invitations
resp = client.post(f"/v1/interviews/{interview_id}/start").raise_for_status().json()
print(resp["message"])

ID=$(curl -s -X POST https://api.ontora.com/v1/interviews \
  -H "X-API-Key: $ONTORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "'$ONTORA_WORKSPACE_ID'",
    "name": "Q2 facility-ops interviews",
    "goal": "Map current scheduling workflows and identify automation opportunities",
    "channel": "in_app_chat"
  }' | jq -r .id)

curl -X POST https://api.ontora.com/v1/interviews/$ID/question-sets \
  -H "X-API-Key: $ONTORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily scheduling",
    "questions": [{"question_text": "Walk me through how this morning went.", "is_required": true}]
  }'

curl -X POST https://api.ontora.com/v1/interviews/$ID/contacts/bulk \
  -H "X-API-Key: $ONTORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contacts":[{"name":"Sam","email":"sam@example.com"}]}'

curl -X POST https://api.ontora.com/v1/interviews/$ID/start \
  -H "X-API-Key: $ONTORA_API_KEY"

# Create + start in one step (topics and contacts come from the YAML)
ontora campaigns create -c campaign.yaml --start

# Or, if you want to add contacts from a CSV between create and start:
ID=$(ontora campaigns create -c campaign.yaml --json | jq -r .id)
ontora contacts import $ID contacts.csv
ontora campaigns start $ID

Knowing when it’s done

Don’t poll. Subscribe to the synthesis.completed webhook — it fires once the synthesis pipeline finishes, and the report is queryable immediately after.

curl -X POST https://api.ontora.com/v1/webhook-endpoints \
  -H "X-API-Key: $ONTORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "8f4a2c10-5d3b-4e6f-9a71-2b8c0d5e7f31",
    "url": "https://example.com/webhooks/ontora",
    "events": ["synthesis.completed"]
  }'

If you can’t run a webhook receiver, fall back to polling GET /v1/interviews/{id} every minute and watching the status field — but webhooks are strongly preferred.

Common follow-ups

Export the report as Markdown.
Run a GraphRAG query over the transcripts.

Get started

Core concepts

Guides

MCP server

CLI

Webhooks

Launch a campaign

Prerequisites

How launching works

End-to-end script

Knowing when it’s done

Common follow-ups

​Prerequisites

​How launching works

​End-to-end script

​Knowing when it’s done

​Common follow-ups

Prerequisites

How launching works

End-to-end script

Knowing when it’s done

Common follow-ups