API integration guide

Examples of Tadeus API usage

A step-by-step walkthrough for building, deploying, and reading back automated voice campaigns programmatically. Every call hits the Integration API at tadeus.net/api/integration/v1.

PythoncURLRESTWebhooks-ready

Quick setup

Install the two dependencies these examples use, then keep your key id and secret in a local .env file. You generate both in your Tadeus dashboard under API access.

pip install requests python-dotenv

Campaign setup

01

Authenticate every request

The Integration API is keyed, not session-based. Send your key id and secret as headers on every call. Load them from the environment so they never end up in source control.

import os
import requests
from dotenv import load_dotenv

load_dotenv()

BASE_URL = "https://tadeus.net/api/integration/v1"

HEADERS = {
    "X-API-KEY-ID": os.environ["TADEUS_API_KEY_ID"],
    "X-API-SECRET": os.environ["TADEUS_API_SECRET"],
    "Content-Type": "application/json",
}

# Quick check: read your organisation
org = requests.get(f"{BASE_URL}/organisation/", headers=HEADERS)
print(org.status_code, org.json())
02

Create a template

A template defines how the agent interviews and what structured output you expect back. You reuse one template across many campaigns.

template = requests.post(
    f"{BASE_URL}/templates/",
    headers=HEADERS,
    json={
        "name": "Benefits enrolment check-in",
        "interview_prompt": (
            "Interview an employee just after open enrolment. "
            "Confirm which plan they chose and whether anything "
            "was unclear. Ask one follow-up when an answer is vague."
        ),
        "output_schema": {
            "plan_chosen": "string",
            "confusion_points": "string[]",
            "needs_followup": "boolean",
        },
        "status": "published",
    },
).json()

template_uuid = template["uuid"]
print(template_uuid)
Response
{
  "uuid": "8d1f6c2a-9b40-4e11-bb7a-2f1c0e9a77d3",
  "name": "Benefits enrolment check-in",
  "version": 1,
  "status": "published",
  "created_at": "2026-01-12T09:30:00Z"
}
03

Create a campaign

A campaign points at a template and controls access. Set access_type to invite_only for a named workforce, or open for a public link. max_sessions is a safety cap.

campaign = requests.post(
    f"{BASE_URL}/campaigns/",
    headers=HEADERS,
    json={
        "name": "Q1 enrolment readiness",
        "template_uuid": template_uuid,
        "type": "survey",
        "access_type": "invite_only",
        "max_sessions": 5000,
    },
).json()

campaign_uuid = campaign["uuid"]
Response
{
  "uuid": "c4a7e0b1-2d33-4f88-9c10-7b6e5a4d3f21",
  "name": "Q1 enrolment readiness",
  "type": "survey",
  "access_type": "invite_only",
  "active": true,
  "created_at": "2026-01-12T09:31:14Z"
}

Invitations & sessions

04

Invite a participant

For an invite-only campaign, add a participant by email. Each invite creates a session that participant can complete in their own language, on their own time.

requests.post(
    f"{BASE_URL}/campaigns/{campaign_uuid}/invite/",
    headers=HEADERS,
    json={"email": "[email protected]", "name": "Alex Doe"},
)
05

Bulk invite participants

Send a whole cohort in one call. Tadeus interviews everyone in parallel, so a 5,000-person rollout does not become 5,000 scheduled calls.

roster = [
    {"email": "[email protected]"},
    {"email": "[email protected]"},
    {"email": "[email protected]"},
]

requests.post(
    f"{BASE_URL}/campaigns/{campaign_uuid}/bulk-invite/",
    headers=HEADERS,
    json={"participants": roster},
)
06

Create an anonymous session

Need responses with no participant attached? Create a session directly and set email_capture_mode to none. People feel safely unwatched, so they speak more freely.

session = requests.post(
    f"{BASE_URL}/sessions/",
    headers=HEADERS,
    json={
        "campaign_uuid": campaign_uuid,
        "email_capture_mode": "none",
        "attempts_allowed": 1,
    },
).json()

session_uuid = session["uuid"]
Response
{
  "uuid": "f02b9d51-7a6e-4c0b-8d2f-1e9c4a6b8021",
  "campaign_uuid": "c4a7e0b1-2d33-4f88-9c10-7b6e5a4d3f21",
  "status": "not_started",
  "email_capture_mode": "none",
  "attempts_allowed": 1,
  "created_at": "2026-01-12T09:33:02Z"
}
07

List sessions

Track progress by polling sessions for a campaign. Filter by status to find the ones that have completed and are ready to read.

sessions = requests.get(
    f"{BASE_URL}/sessions/",
    headers=HEADERS,
    params={"campaign_uuid": campaign_uuid, "status": "completed"},
).json()

print(sessions["count"], "completed sessions")

Collecting results

08

Read structured results

Every completed session returns a structured result: a summary plus comprehension signals (confidence, relevance, sentiment, engagement) and your template's output_json. No audio to listen back to.

results = requests.get(
    f"{BASE_URL}/results/",
    headers=HEADERS,
    params={"campaign_uuid": campaign_uuid},
).json()

for r in results["results"]:
    print(r["short_summary"], r["confidence"], r["sentiment"])
Response
{
  "count": 1,
  "next": null,
  "results": [
    {
      "id": 4821,
      "session_uuid": "f02b9d51-7a6e-4c0b-8d2f-1e9c4a6b8021",
      "campaign_uuid": "c4a7e0b1-2d33-4f88-9c10-7b6e5a4d3f21",
      "short_summary": "Chose the high-deductible plan; found the dependant section confusing.",
      "output_json": {
        "plan_chosen": "high_deductible",
        "confusion_points": ["dependant section"],
        "needs_followup": true
      },
      "confidence": 0.94,
      "relevance": 0.91,
      "sentiment": 0.2,
      "engagement": 0.86,
      "validated": true,
      "created_at": "2026-01-12T10:04:55Z"
    }
  ]
}
09

Pull a transcript

When you need the raw exchange, read the transcript text directly. Tadeus stores the transcript, never the audio.

transcript = requests.get(
    f"{BASE_URL}/transcripts/{transcript_uuid}/",
    headers=HEADERS,
).json()

print(transcript["text"])
10

Generate cross-session insights

Roll every result in a campaign into one synthesis. Kick off the job, then read the insight back, or export it as Markdown or PDF for the steering committee.

# Kick off synthesis across the whole campaign
requests.post(
    f"{BASE_URL}/campaigns/{campaign_uuid}/generate-insights/",
    headers=HEADERS,
)

# Read the insight back
insights = requests.get(
    f"{BASE_URL}/insights/",
    headers=HEADERS,
    params={"campaign_uuid": campaign_uuid},
).json()

insight_uuid = insights["results"][0]["uuid"]

# Export it as Markdown
md = requests.get(
    f"{BASE_URL}/insights/{insight_uuid}/md/",
    headers=HEADERS,
)
print(md.text)

Full endpoint reference, request schemas, and response models live in the API documentation.

Build it into your platform. Start with a key.

Spin up a free Tadeus account, generate an API key, and run your first campaign end to end in an afternoon.

Start for freeExplore the platform
Or book a demo for your team