outbound_calls
Place Call
Place one outbound call with an agent, through an outbound trunk. Use for a single call that is not part of a campaign — a one-off dial.
It takes its turn in the organization's rotation like a campaign does, and it
is dialled once: one attempt, no retry, no calling-hours trim. Give at to
name an instant instead — that jumps the rotation and is never brought
forward into a free slot.
Place Call › Request Body
agent_iddestinationtrunk_idWhen to place the call. Absent means it takes its turn in the organization's rotation, on the next free slot; a value is an instant somebody named, which jumps the rotation and is never brought forward into a free slot. A call that belongs to no campaign has no calling hours, so any instant is kept. Must carry a UTC offset (2026-09-10T11:00:00Z or 2026-09-10T13:00:00+02:00); without one the request is refused with 422 naming the field, so the call is never placed at a guessed-at moment.
told_fieldsPlace Call › Responses
Successful Response
attempts_spentcreated_atdue_nowidstatusOne contact's place in the state machine outbound-calls.md calls
single-writer and idempotent.
EXHAUSTED is we are finished with this number — the attempt budget is
gone, the provider confirmed the destination will never work, or the
organization's own retention window destroyed the number while the contact
was still waiting for a turn and there is nothing left to dial.
EXCLUDED is the client said not to call this person, and only a client
ever writes it. Keeping them apart is what lets "excluding a contact cancels
its pending calls" be re-openable while a confirmed-invalid number is not.
There is no pending. A contact is dialable the moment it exists —
"activating a campaign does not queue its contacts" — so it is written
SCHEDULED and there is no earlier state for it to sit in. A member nothing
writes is a state a reader has to ask about and nobody can reach.
updated_atList Campaigns
List this organization's campaigns, newest first. Use when showing the catalogue of campaigns, or checking what already exists before creating another. Changes nothing.
query Parameters
statusList Campaigns › Responses
Successful Response
agent_idcollection_told_fieldscontact_sourceWhere a campaign's contacts come from.
COLLECTION names docs/features/custom-data.md's stored collection. This
slice holds the id and nothing else: the read is an injected ContactSource,
bound to nothing today.
created_atidnameorg_idprovider_failure_streakstatusWhere a campaign is in its life.
PAUSED is one state whoever caused it — see PauseOrigin. There is no
separate "stopped by the provider" status, because resuming is the same
operation either way and a second status would double every read of "is this
campaign dialling".
timezonetrunk_idupdated_atwarningsCreate Campaign
Open a campaign: an agent, an outbound trunk, a retry policy and calling hours. Use when many contacts need the same agent to call them under one policy.
It opens as a draft with sensible values already filled in, which you can see and change. Nothing is dialled until you activate it. A campaign drawn from a custom-data collection imports that collection's rows as it is created.
Create Campaign › Request Body
agent_idnametimezonetrunk_idcollection_told_fieldscontact_sourceWhere a campaign's contacts come from.
COLLECTION names docs/features/custom-data.md's stored collection. This
slice holds the id and nothing else: the read is an injected ContactSource,
bound to nothing today.
Create Campaign › Responses
Successful Response
agent_idcollection_told_fieldscontact_sourceWhere a campaign's contacts come from.
COLLECTION names docs/features/custom-data.md's stored collection. This
slice holds the id and nothing else: the read is an injected ContactSource,
bound to nothing today.
created_atidnameorg_idprovider_failure_streakstatusWhere a campaign is in its life.
PAUSED is one state whoever caused it — see PauseOrigin. There is no
separate "stopped by the provider" status, because resuming is the same
operation either way and a second status would double every read of "is this
campaign dialling".
timezonetrunk_idupdated_atwarningsGet Campaign
Read one campaign, its calling hours, and anything they were warned about. Use when opening a specific campaign by id. Changes nothing.
path Parameters
campaign_idGet Campaign › Responses
Successful Response
agent_idcollection_told_fieldscontact_sourceWhere a campaign's contacts come from.
COLLECTION names docs/features/custom-data.md's stored collection. This
slice holds the id and nothing else: the read is an injected ContactSource,
bound to nothing today.
created_atidnameorg_idprovider_failure_streakstatusWhere a campaign is in its life.
PAUSED is one state whoever caused it — see PauseOrigin. There is no
separate "stopped by the provider" status, because resuming is the same
operation either way and a second status would double every read of "is this
campaign dialling".
timezonetrunk_idupdated_atwarningsUpdate Campaign
Change a campaign's name, agent, trunk, timezone or retry policy. Use when a campaign's own settings need to change — only the fields given.
It also takes the collection columns the agent is told about and the
questions each call answers — and the questions need the collection read,
because their kinds are the collection's. Hence contacts here: without it
every save of a campaign that asks anything is refused as a deployment that
cannot read a collection.
path Parameters
campaign_idUpdate Campaign › Request Body
Update Campaign › Responses
Successful Response
agent_idcollection_told_fieldscontact_sourceWhere a campaign's contacts come from.
COLLECTION names docs/features/custom-data.md's stored collection. This
slice holds the id and nothing else: the read is an injected ContactSource,
bound to nothing today.
created_atidnameorg_idprovider_failure_streakstatusWhere a campaign is in its life.
PAUSED is one state whoever caused it — see PauseOrigin. There is no
separate "stopped by the provider" status, because resuming is the same
operation either way and a second status would double every read of "is this
campaign dialling".
timezonetrunk_idupdated_atwarningsActivate Campaign
Start dialling this campaign, or resume one that stopped. Use once the campaign's agent, list and hours are right and it should actually call people — this makes the platform phone somebody.
It queues nothing: the campaign joins the organization's rotation and takes the next free slot. Resuming keeps the record of why it stopped.
Refused, saying which, for a campaign already dialling, a completed one (copy it instead), one whose retry policy is blank, one whose agent no arrangement of its profile can hold, and one with no calling hours at all.
path Parameters
campaign_idActivate Campaign › Responses
Successful Response
agent_idcollection_told_fieldscontact_sourceWhere a campaign's contacts come from.
COLLECTION names docs/features/custom-data.md's stored collection. This
slice holds the id and nothing else: the read is an injected ContactSource,
bound to nothing today.
created_atidnameorg_idprovider_failure_streakstatusWhere a campaign is in its life.
PAUSED is one state whoever caused it — see PauseOrigin. There is no
separate "stopped by the provider" status, because resuming is the same
operation either way and a second status would double every read of "is this
campaign dialling".
timezonetrunk_idupdated_atwarningsLink Collection
Give a campaign that has no list one, and optionally take records from it. Use once, when a campaign should draw its contacts from a custom-data collection rather than numbers added by hand.
Which column holds the number comes with it and is chosen once. Refused for a campaign that already draws from a list: a campaign that needs a different one is another campaign.
path Parameters
campaign_idLink Collection › Request Body
Link Collection › Responses
Successful Response
Add Contacts
Add numbers to a campaign's list. Use to hand-add specific phone numbers to a campaign, rather than importing from a collection.
Rows this campaign already holds, or that are not a phone number under the
organization's default country, come back in rejected with the reason;
nothing is silently dropped.
path Parameters
campaign_idAdd Contacts › Request Body
Add Contacts › Responses
Successful Response
Add Contacts From Collection
Add the records a filter finds to a campaign's list. Use after a campaign is already linked to a collection, to pull in records matching a filter.
The body is the question the client was looking at — the collection's own
filters, and the records they picked or unticked — never a list of rows.
Records with no usable phone number come back in rejected with the reason.
path Parameters
campaign_idAdd Contacts From Collection › Request Body
Add Contacts From Collection › Responses
Successful Response
Remove Contacts From Collection
Take the records a filter finds back out of a campaign's list. Use when records matching a filter should stop being part of the campaign entirely — not merely excluded from calling.
A record the campaign never held is not an error. A call already placed is not cancelled by this — that is excluding the contact.
path Parameters
campaign_idRemove Contacts From Collection › Request Body
Remove Contacts From Collection › Responses
Successful Response
removedSet Campaign Hours
Replace a campaign's calling hours: slots per weekday, in its own timezone.
Use once the hours are decided; preview_campaign_hours first to see what
the change does to calls already waiting.
No slot may cross midnight, no two may overlap, and a schedule that opens on
no day at all is rejected. Hours outside the Spanish commercial-calling window
are warned about and saved as asked. Waiting calls that keep to the hours (a
timed retry, or a callback the client asked to keep to them) and that the new
hours do not hold are moved to the first later day whose hours hold that same
local time (or, when no day does, to the next opening); every other time
somebody named stays where it is and is counted in warnings.
preview_campaign_hours gives both counts before you save.
path Parameters
campaign_idSet Campaign Hours › Request Body
Set Campaign Hours › Responses
Successful Response
agent_idcollection_told_fieldscontact_sourceWhere a campaign's contacts come from.
COLLECTION names docs/features/custom-data.md's stored collection. This
slice holds the id and nothing else: the read is an injected ContactSource,
bound to nothing today.
created_atidnameorg_idprovider_failure_streakstatusWhere a campaign is in its life.
PAUSED is one state whoever caused it — see PauseOrigin. There is no
separate "stopped by the provider" status, because resuming is the same
operation either way and a second status would double every read of "is this
campaign dialling".
timezonetrunk_idupdated_atwarningsPreview Campaign Hours
Count what these hours would do to the calls set for an exact time,
without saving them: how many that keep to the hours would move, and how many
named times would stay outside them. Use before set_campaign_hours, to show
the effect before committing to it.
Ask before set_campaign_hours so whoever is saving can be told both counts,
and confirm. Only calls still to come are counted: one already due rings
while the hours are open and moves while they are closed. Nothing is written.
path Parameters
campaign_idPreview Campaign Hours › Request Body
Preview Campaign Hours › Responses
Successful Response
movesHow many waiting calls that keep to the calling hours -- a timed retry, or a callback the client asked to keep to them -- these hours would not hold. Saving the hours moves each to the first later day whose hours hold the same local time, or, when no day's hours hold it, to the next opening.
stays_outsideHow many waiting calls set for a time a person, an integration or a caller named these hours would not hold. Saving the hours leaves each at its time: this is a warning, not a move.
Pause Campaign
Stop dialling this campaign. Use when a running campaign needs to stop
without losing it — resume later with activate_campaign. A call already in
progress is never cut.
path Parameters
campaign_idPause Campaign › Responses
Successful Response
agent_idcollection_told_fieldscontact_sourceWhere a campaign's contacts come from.
COLLECTION names docs/features/custom-data.md's stored collection. This
slice holds the id and nothing else: the read is an injected ContactSource,
bound to nothing today.
created_atidnameorg_idprovider_failure_streakstatusWhere a campaign is in its life.
PAUSED is one state whoever caused it — see PauseOrigin. There is no
separate "stopped by the provider" status, because resuming is the same
operation either way and a second status would double every read of "is this
campaign dialling".
timezonetrunk_idupdated_atwarningsGet Campaign Summary
How far a campaign has got: contacts by status, attempts by outcome, connect rate, and whether the organization's spend gate is what is stopping it from dialling right now. Use when showing campaign progress. Changes nothing.
path Parameters
campaign_idGet Campaign Summary › Responses
Successful Response
as_ofattempts_spentcampaign_idcontacts_without_numberdue_laterdue_nowstatusWhere a campaign is in its life.
PAUSED is one state whoever caused it — see PauseOrigin. There is no
separate "stopped by the provider" status, because resuming is the same
operation either way and a second status would double every read of "is this
campaign dialling".
unclassified_pickupsExclude Contact
Stop calling this contact. Use when one person should be left out of the rotation without touching the rest of the campaign's list. A call already in progress is never cut. Refused for a contact already done or exhausted: there is nothing left to stop.
path Parameters
contact_idExclude Contact › Responses
Successful Response
attempts_spentcreated_atdue_nowidstatusOne contact's place in the state machine outbound-calls.md calls
single-writer and idempotent.
EXHAUSTED is we are finished with this number — the attempt budget is
gone, the provider confirmed the destination will never work, or the
organization's own retention window destroyed the number while the contact
was still waiting for a turn and there is nothing left to dial.
EXCLUDED is the client said not to call this person, and only a client
ever writes it. Keeping them apart is what lets "excluding a contact cancels
its pending calls" be re-openable while a confirmed-invalid number is not.
There is no pending. A contact is dialable the moment it exists —
"activating a campaign does not queue its contacts" — so it is written
SCHEDULED and there is no earlier state for it to sit in. A member nothing
writes is a state a reader has to ask about and nobody can reach.
updated_atInclude Contact
Put an excluded contact back. Use when a previously excluded contact should be called again. It rejoins the rotation immediately. Refused for a contact that was never excluded or has since finished, and when the list has been filled back up to its bound while this contact was off it.
path Parameters
contact_idInclude Contact › Responses
Successful Response
attempts_spentcreated_atdue_nowidstatusOne contact's place in the state machine outbound-calls.md calls
single-writer and idempotent.
EXHAUSTED is we are finished with this number — the attempt budget is
gone, the provider confirmed the destination will never work, or the
organization's own retention window destroyed the number while the contact
was still waiting for a turn and there is nothing left to dial.
EXCLUDED is the client said not to call this person, and only a client
ever writes it. Keeping them apart is what lets "excluding a contact cancels
its pending calls" be re-openable while a confirmed-invalid number is not.
There is no pending. A contact is dialable the moment it exists —
"activating a campaign does not queue its contacts" — so it is written
SCHEDULED and there is no earlier state for it to sit in. A member nothing
writes is a state a reader has to ask about and nobody can reach.
updated_at