Skip to main content
A campaign calls a list of phone numbers with a voice agent. Each number is a campaign item with its own variables, so the agent can greet every contact by name or talk about their own order. Clarity dials the items in the background, a few at a time, and records each call as a conversation. For a single call, dispatch it directly.

​
Lifecycle

Starting, scheduling and cancelling a campaign changes what is dialed live, so these calls need the publish permission. Your organization API key has it.

​
Create a campaign

1

Create it as a draft with its items

The response is 201 with { "campaign": {...}, "items": [...] }. Without a start_time the campaign is a draft.
2

Add more items while it is a draft

The response is 201 with { "items": [...] }.
3

Start it

start sets start_time to now and answers with { "campaign": {...} } in status scheduled. Clarity’s scheduler turns it running shortly after and dials within the calling window.
To schedule instead of starting now, send a start_time when you create or update the campaign.

​
Campaign fields

​
string
required
Display name.
​
string
The agent that places the calls. Items can override it. The agent must be in the project and published (409 AGENT_NOT_PUBLISHED otherwise); an unknown id is refused with 422. An item with no agent of its own on a campaign with no agent fails when it is dialed.
​
string
The caller ID. When it is not an outbound-enabled number of the project, it is ignored and the agent’s own caller ID is used, the same order as for dispatch. Unlike dispatch-call, the campaign does not fail.
​
string
ISO 8601 with a time zone offset, for example 2026-11-01T09:00:00-05:00. Setting it schedules the campaign; setting it to null on update turns a scheduled campaign back into a draft.
​
integer
default:"5"
How many calls run at the same time. From 5 to 20.
​
integer
default:"0"
How many more times to dial a number whose call did not connect.
​
integer
default:"0"
How long to wait before each retry.
​
object
When dialing is allowed. null or absent means any time.
  • start, end: HH:MM, 24-hour. Calls start at or after start and before end. An end earlier than start wraps past midnight.
  • days: ISO weekdays, Monday 1 to Sunday 7. Absent or empty means every day.
  • timezone: an IANA zone such as Europe/London.
The window controls when calls start; a call in progress at end is not cut off.
​
boolean
default:"false"
The default for each item’s callback. See Callbacks.
​
array
The contacts to call. You can also add them later.

​
Item fields

​
string
required
The number to call, in E.164 format. A number that cannot be parsed is stored with status invalid and never dialed.
​
string
The contact’s name. The agent can use it as the contact_name variable.
​
object
Values for the variables your agent’s prompt uses, keyed by variable name, for example {"plan": "Pro"} for a plan variable. Values must be strings. A variable the prompt does not use is ignored. A contact_name key here takes precedence over name.
​
string
Overrides the campaign’s agent for this contact.
​
boolean
Whether this contact can ask to be called back. Defaults to the campaign’s callback.

​
How items are dialed

  • Connected calls end the item. A call that reached someone is ended. Clarity does not yet tell a voicemail from a person in this step, so a call picked up by voicemail also counts as connected.
  • Unanswered calls are retried. Busy, no answer, declined, or rang and dropped: the item goes back to scheduled for another attempt after retry_delay_seconds, until retries is used up. Then it is failed with a reason such as no answer after 3 attempt(s).
  • Some failures are never retried. The carrier answers that the number does not exist or is incomplete (SIP 404, 484, 485 or 604).
  • The campaign ends on its own when no item is scheduled or ongoing.
Each item’s attempt_count counts dials so far, and its conversation_id points to the latest call. Conversations placed by a campaign carry campaign_id and campaign_item_id, so you can filter and join them.

​
Callbacks

When an item has callback: true, the agent is asked to note at the end of the call whether the contact wants a callback and when. If they do, and the campaign is still running, Clarity creates a new item for the requested time with the same name, number and variables, and marks the original rescheduled. A requested time in the past is dialed as soon as possible.

​
Monitor a campaign

  • completion.pct is the share of items in a final status, as a percentage.
  • timeseries groups items by the minute they last changed.
To see each contact, read the campaign with its items: GET /v1/projects/{projectId}/campaigns/{id} returns { "campaign": {...}, "items": [...] }. Items there also carry duration_sec (total call time) and resolution (resolved, unresolved or null). To list campaigns, use GET /v1/projects/{projectId}/campaigns. Filter with status, comma-separated, for example ?status=scheduled,running. Each campaign carries item_counts by status.

​
Change, stop and reuse

All paths are under /v1/projects/{projectId}. A request outside the allowed status answers 409.
  • Cancel lets calls in progress finish. It stops new dials, retries and callbacks.
  • Resume dials the items that had not reached a final status. A campaign canceled before its scheduled time resumes at that time; otherwise it resumes now.
  • Clone creates a new draft named <name> (copy) with the same settings and contacts, and none of the results. Callback items are not copied.
  • Changing an item’s phone_number re-checks it: a bad number turns the item invalid, a good one makes it scheduled again.