Skip to main content
POST
Create a dialer campaign

Authorizations

Authorization
string
header
required

Dashboard JWT token from Clerk

Headers

Idempotency-Key
string

Stripe-style idempotency token. Pass a stable, client-generated value (1-255 chars) to dedupe retries on transient timeouts. The same key+credential+path replays the original response for 24h on 2xx (5min on 4xx, 30s on 5xx). Returns 409 if a concurrent request with the same key is already in flight; replayed responses include the Idempotency-Replay: true response header.

Required string length: 1 - 255
X-Test-Mode
enum<string>

Sandbox opt-in for Clerk-session-authenticated requests. Set to true to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response meta.test_mode: true. Ignored for live API keys (dv_live_sk_*) — server-to-server clients must use a test-prefixed key (dv_test_sk_*) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.

Available options:
true,
false

Body

application/json
name
string

Campaign display name.

mode
string

Dial strategy: 'preview' (agent reviews + clicks to dial), 'progressive', 'predictive', or 'agentless' (broadcast, no agent leg).

caller_id_e164
string

Default outbound caller-ID in E.164 format. Must be a number this org owns.

pacing_ratio
number

Predictive/progressive dial-to-agent ratio. 0.8-3.0, default 1.2.

max_abandon_rate
number

FCC abandon-rate ceiling for this campaign, as a fraction (e.g. 0.03 = 3%). Cannot exceed the platform's 3% ceiling.

target_service_level_seconds
number

Target seconds-to-answer used by the predictive pacer. 5-120, default 20.

application_sid
string

Optional explicit Jambonz voice-control-plane application override. Omit to use the mode/AMD-resolved default.

agent_skills_required
array

Required agent skills for this campaign — legacy string array (e.g. ['french']) or structured {skill, min_level, weight} objects.

call_script_id
string

Optional legacy call-script reference.

recording_enabled
boolean

Whether calls in this campaign are recorded. Requires recording_consent_acknowledged=true.

amd_enabled
boolean

Whether answering-machine detection runs on each dialed leg.

dispatch_mode
string

'human' (default, agent-fronted) or 'voice_agent' (each leg connects to the AI voice agent named by voice_agent_id, dispatched via POST /campaigns/:id/batch-dispatch).

voice_agent_id
string

Required when dispatch_mode='voice_agent'; must reference an existing agent in this workspace.

concurrency_limit
number

Max simultaneous in-flight legs for voice-agent batch dispatch. 1-200, default 10.

broadcast_message_url
string

HTTPS URL of the message Jambonz plays on answer. Required when mode='agentless', forbidden otherwise.

voicemail_message_url
string

HTTPS voicemail-drop audio URL played when AMD detects a machine. Only valid for agent-driven modes.

amd_sensitivity
string

AMD detection sensitivity: 'low', 'medium', or 'high'. Only meaningful when amd_enabled=true.

preview_decision_seconds
number

Per-campaign override of how long a preview-mode agent has to decide before the claim auto-skips. Only valid for mode='preview'.

metadata
object

Free-form operator metadata (e.g. TCPA quiet-hours override, disposition codes).

retry_policy
object

Per-outcome retry backoff schedule keyed by outcome bucket (no_answer, busy, machine, machine_silence, failed).

caller_id_pool
array

Local-presence caller-ID rotation pool. Every entry must be owned by this org. Required (non-empty) when caller_id_strategy is not 'single'.

caller_id_strategy
string

Caller-ID assignment strategy: 'single' (default) or 'npa_match' (local-presence rotation from caller_id_pool).

campaign_script
object

Optional human-agent guided-dialog script (sections + branches). Omitted campaigns persist the canonical empty shape.

Operator's two-party-consent acknowledgement. Required when recording_enabled=true.

best_time_to_dial
boolean

When true, contacts uploaded to this campaign are enrolled at their highest-answer-probability window instead of list order.

Response

The created campaign.

The created campaign.

data
object

The created campaign row, echoing every submitted field plus server-assigned id and status: 'draft'.

meta
object