Campaigns CRUD

All campaign endpoints require an API key with the appropriate scope. Campaigns are scoped to the tenant bound to your API key.

Create a campaign

curl -X POST https://api.yotel.in/api/v1/campaigns \
  -H "Authorization: Bearer yt_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "May outreach",
    "dial_mode": "progressive",
    "voice_agent_id": "va_abc123"
  }'

from yotel import Client

client = Client(api_key="yt_live_YOUR_KEY")
campaign = client.campaigns.create(
    name="May outreach",
    dial_mode="progressive",
    voice_agent_id="va_abc123",
)
print(campaign.id)

import { YotelClient } from "@yotel/client";

const client = new YotelClient({ apiKey: "yt_live_YOUR_KEY" });
const campaign = await client.campaigns.create({
  name: "May outreach",
  dial_mode: "progressive",
  voice_agent_id: "va_abc123",
});
console.log(campaign.id);

Request body

Field	Type	Required	Description
`name`	string	Yes	Campaign display name
`dial_mode`	string	Yes	`"preview"`, `"progressive"`, or `"predictive"`
`voice_agent_id`	string	No	Attach a voice agent to handle answered calls
`post_answer_action`	string	No	`"connect_agent"` (default), `"connect_voice_agent"`, or `"run_flow"`
`max_concurrent`	integer or `null`	No	The most calls this campaign keeps up at once. Omit it (or send `null`) for all of your channel allocation — see below. A number pins the campaign below that.
`predictive_target_abandon`	number	No	Target abandon rate for predictive mode (max `0.03` — TRAI hard cap)
`predictive_max_wait_s`	number	No	Max seconds an answered lead waits for an agent in predictive mode

`max_concurrent` and your channel allocation

Your account is allocated a number of concurrent channels on the carrier trunk (what Yotel calls the channel allocation; ask your account manager for the figure, or read channels_allocated from GET /api/telephony/channels/usage). A campaign with max_concurrent null keeps as many calls up as that allocation allows, counting every call your account has up — other campaigns, inbound calls and agent dials included — so the allocation is used completely without any campaign overrunning it. Two things to know:

It is a ceiling that follows the allocation, not a fixed number. Raise the allocation and every null campaign dials more; nothing on the campaign needs to change.
Enforcement requires an active trunk. If Yotel has no active trunk declared for your carrier, there is no allocation to follow and a null campaign falls back to 10 concurrent calls per API process (the previous default). GET /api/telephony/channels/usage reports whether the allocation is enforced under ceilings.channels.enforced.
Two campaigns sharing one allocation are first-come-first-served. The allocation is a ceiling, not a share. If both must make progress at once, set an explicit max_concurrent on each so their sum fits.

A numeric max_concurrent behaves as it always has: a per-campaign ceiling, still bounded by the allocation when one is enforced. If your account also uses a voice agent, that agent’s own max_concurrent applies too — the tightest of the three is what you get. If your organisation set a default in the dashboard (Settings → General → Max Concurrent), a request that omits the field inherits it; an explicit null does not. Scope: campaigns:write | Status: 201 Created

Response

Returns a CampaignResponse object with id, name, dial_mode, status ("draft"), timestamps, and all configured fields.

List campaigns

Returns all campaigns for the tenant bound to your API key.

curl https://api.yotel.in/api/v1/campaigns \
  -H "Authorization: Bearer yt_live_YOUR_KEY"

campaigns = client.campaigns.list()

const campaigns = await client.campaigns.list();

Scope: campaigns:read | Status: 200 OK

Get a campaign

curl https://api.yotel.in/api/v1/campaigns/{campaign_id} \
  -H "Authorization: Bearer yt_live_YOUR_KEY"

campaign = client.campaigns.get("campaign_id")

const campaign = await client.campaigns.get("campaign_id");

Scope: campaigns:read | Status: 200 OK Returns 404 if the campaign does not exist or belongs to a different tenant.

Update a campaign

PATCH semantics — only include the fields you want to change.

curl -X PATCH https://api.yotel.in/api/v1/campaigns/{campaign_id} \
  -H "Authorization: Bearer yt_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated name"}'

campaign = client.campaigns.update("campaign_id", name="Updated name")

const campaign = await client.campaigns.update("campaign_id", {
  name: "Updated name",
});

Scope: campaigns:write | Status: 200 OK

Clearing a field

An omitted field and an explicit null are different requests. Omit a field to leave it alone; send null to clear it. Only caller_id, flow_id, voice_agent_id, description, script, notes, and max_concurrent may be cleared — a null on any other field returns 422.

{ "caller_id": null }

Clearing caller_id makes the campaign rotate through the tenant’s own numbers again. Clearing max_concurrent puts the campaign back onto your channel allocation (see max_concurrent and your channel allocation).

Editing a running campaign

PATCH on a running campaign returns 409. The dialer reads its configuration once at start; pause the campaign, edit it, then resume — the resumed dialer picks up the new values.

Delete a campaign

curl -X DELETE https://api.yotel.in/api/v1/campaigns/{campaign_id} \
  -H "Authorization: Bearer yt_live_YOUR_KEY"

client.campaigns.delete("campaign_id")

await client.campaigns.delete("campaign_id");

Scope: campaigns:write | Status: 204 No Content Returns 409 Conflict if the campaign is in a state that cannot be deleted (e.g., currently running).

Errors

Status	Condition
`404`	Campaign not found or belongs to another tenant
`409`	Campaign is in a state that prevents the operation (including `PATCH` while `running`)
`422`	Validation error (e.g., `predictive_target_abandon > 0.03`, or `null` on a required field)

Overview

Campaigns

Leads

Calls & Recordings

Agents

Voice Agents

AI Sessions

Webhook Management

API Keys

Create a campaign

Request body

`max_concurrent` and your channel allocation

Response

List campaigns

Get a campaign

Update a campaign

Clearing a field

Editing a running campaign

Delete a campaign

Errors

​Create a campaign

​Request body

​max_concurrent and your channel allocation

​Response

​List campaigns

​Get a campaign

​Update a campaign

​Clearing a field

​Editing a running campaign

​Delete a campaign

​Errors

Create a campaign

Request body

`max_concurrent` and your channel allocation

Response

List campaigns

Get a campaign

Update a campaign

Clearing a field

Editing a running campaign

Delete a campaign

Errors