Quickstart

This guide walks through the minimum integration: create an API key, launch a campaign, and read the synthesized report.

The examples use the US API host. For a workspace on eu.ontora.com, replace https://api.ontora.com with https://api.eu.ontora.com throughout.

1. Create an API key

API keys are workspace-scoped. From the Ontora dashboard:

Open Developer → API Keys (profile menu).
Click Create API key.
Pick the access level. For this quickstart, Read-only is enough (read scope).
Copy the key (it starts with ont_). You will not be able to see it again.

Treat API keys like passwords. Store them in a secret manager — never commit them to source control.

2. Authenticate

Every request takes an X-API-Key header.

export ONTORA_API_KEY="ont_..."

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

import os, httpx

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

campaigns = client.get("/v1/interviews").json()

const res = await fetch("https://api.ontora.com/v1/interviews", {
  headers: { "X-API-Key": process.env.ONTORA_API_KEY! },
});
const campaigns = await res.json();

3. Launch a campaign

Create a campaign, add a topic with questions, add contacts, then start it. You’ll need your workspace ID — API keys are workspace-scoped and the ID is shown alongside the key in Developer → API Keys.

# 1. Create (draft)
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 pain points",
    "channel": "in_app_chat"
  }' | jq -r .id)

# 2. Add a topic with at least one question
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 shifts were assigned this morning.", "is_required": true}]
  }'

# 3. Add contacts
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"}]}'

# 4. Start — sends each contact an email with their personal interview link
curl -X POST https://api.ontora.com/v1/interviews/$ID/start \
  -H "X-API-Key: $ONTORA_API_KEY"

Campaigns can also invite via Slack or Microsoft Teams ("channel": "slack" | "teams", with the workspace integration connected), and a future timeframe_start with "start_immediately": false schedules the invitation send instead of emailing at launch. See Launch a campaign.

4. Pull the synthesis report

Once the campaign has completed conversations, fetch the rendered report as Markdown:

curl https://api.ontora.com/v1/interviews/$ID/export/report \
  -H "X-API-Key: $ONTORA_API_KEY" \
  -o report.md

Or get individual transcripts as a ZIP:

curl https://api.ontora.com/v1/interviews/$ID/export/transcripts \
  -H "X-API-Key: $ONTORA_API_KEY" \
  -o transcripts.zip

5. Ask a question across the campaign

Use the GraphRAG query endpoint to run grounded questions over every transcript:

curl -X POST https://api.ontora.com/v1/interviews/$ID/graph/query \
  -H "X-API-Key: $ONTORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "What are the most painful manual steps in the scheduling workflow?"}'

The response includes the answer, common patterns, and dissenting opinions across respondents.

Get started

Core concepts

Guides

MCP server

CLI

Webhooks

1. Create an API key

2. Authenticate

3. Launch a campaign

4. Pull the synthesis report

5. Ask a question across the campaign

What’s next

Subscribe to webhooks

Connect Claude or Cursor

​1. Create an API key

​2. Authenticate

​3. Launch a campaign

​4. Pull the synthesis report

​5. Ask a question across the campaign

​What’s next

Subscribe to webhooks

Connect Claude or Cursor

1. Create an API key

2. Authenticate

3. Launch a campaign

4. Pull the synthesis report

5. Ask a question across the campaign

What’s next