Campaigns

A campaign places outbound calls to a set of contacts. It ties together the agent that speaks on the call, the phone number the call comes from, and the contact lists that define who to call. Once created, you control the campaign with the start, pause, resume, and cancel operations.

Base URL

https://api.persistence.dev

These endpoints are served under the public /v1 prefix.

Authentication

Every request requires a workspace API key in the X-API-Key header.

curl https://api.persistence.dev/v1/calls/campaigns \
  --header "X-API-Key: $PERSISTENCE_API_KEY"

Endpoints

List campaigns

GET /v1/calls/campaigns — page through your campaigns.

Create campaign

POST /v1/calls/campaigns — create a campaign.

Get campaign

GET /v1/calls/campaigns/{id} — retrieve a campaign and its contact groups.

Update campaign

PATCH /v1/calls/campaigns/{id} — change a campaign’s configuration.

Delete campaign

DELETE /v1/calls/campaigns/{id} — delete a campaign.

List campaign contacts

GET /v1/calls/campaigns/{id}/contacts — see per-contact call status.

List campaign conversations

GET /v1/calls/campaigns/{id}/events — page through conversations produced by the campaign.

Start campaign

POST /v1/calls/campaigns/{id}/start — begin placing calls.

Pause campaign

POST /v1/calls/campaigns/{id}/pause — pause a running campaign.

Resume campaign

POST /v1/calls/campaigns/{id}/resume — resume a paused campaign.

Cancel campaign

POST /v1/calls/campaigns/{id}/cancel — cancel a campaign.

Before you start

A campaign references resources created through the other APIs. Gather these first.

Agent

agentId — the agent that speaks on the call.

Phone number

fromNumber — the number the call comes from, or use a number pool.

Contact lists

contactListIds and dndListIds — who to call and who to skip.

Create a campaign

POST /v1/calls/campaigns requires name, agentId, contactListIds, maxConcurrency, and exactly one of fromNumber or numberPoolId.

Field	Type	Description
`name`	string	Required. Campaign name.
`agentId`	string	Required. Agent that places the calls.
`fromNumber`	string	Caller ID in E.164 format. Mutually exclusive with `numberPoolId`.
`numberPoolId`	string	Number pool used for caller ID rotation. Mutually exclusive with `fromNumber`.
`contactListIds`	array of string	Required. Contact lists to call. Must contain at least one ID.
`maxConcurrency`	integer	Required. Maximum simultaneous calls. Minimum `1`.
`dndListIds`	array of string	Contact lists whose numbers the campaign skips.
`retryPolicy`	object	Retry configuration for campaign calls.
`scheduledAt`	date-time	Required unless `sendNow` is `true`.
`scheduleStart`	string	Optional daily calling-window start in zero-padded `HH:MM`.
`scheduleEnd`	string	Optional daily calling-window end in zero-padded `HH:MM`.
`timezone`	string	IANA time zone used for the schedule.
`sendNow`	boolean	Start the campaign immediately instead of scheduling it.

Pass contactListIds for the audience and dndListIds for numbers to exclude. Both accept IDs from the Campaign audience API; create do-not-disturb lists with type set to dnd.

curl --request POST https://api.persistence.dev/v1/calls/campaigns \
  --header "X-API-Key: $PERSISTENCE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Spring outreach",
    "agentId": "AGENT_ID",
    "fromNumber": "+15551234567",
    "contactListIds": ["CONTACT_LIST_ID"],
    "maxConcurrency": 5
  }'

A 422 indicates the campaign could not be created with the values supplied.

Set scheduleStart and scheduleEnd together. Do not send scheduling fields when sendNow is true.

Control a running campaign

Four operations move a campaign through its lifecycle. Each takes only the campaign ID and returns the updated campaign.

Operation	Endpoint
Start	`POST /v1/calls/campaigns/{id}/start`
Pause	`POST /v1/calls/campaigns/{id}/pause`
Resume	`POST /v1/calls/campaigns/{id}/resume`
Cancel	`POST /v1/calls/campaigns/{id}/cancel`

curl --request POST \
  "https://api.persistence.dev/v1/calls/campaigns/$CAMPAIGN_ID/start" \
  --header "X-API-Key: $PERSISTENCE_API_KEY"

The campaign records pausedAt, resumedAt, stoppedAt, and cancelledAt as these operations are applied, so you can read the current state from the campaign itself.

Campaign fields

Field	Type	Description
`id`	string	Campaign ID.
`name`	string	Campaign name.
`description`	string	Campaign description.
`status`	string	Current campaign status.
`direction`	string	Call direction, `inbound` or `outbound`.
`agentId`	string	Agent that places the calls.
`fromNumber`	string	Number the calls come from.
`lists`	array	Contact lists attached to the campaign, each with an `id` and a `role`.
`maxConcurrency`	integer	Maximum simultaneous calls.
`retryPolicy`	array of integer	Retry schedule for unanswered calls.
`totalContacts`	integer	Number of contacts in the campaign.
`targetCallCount`	integer	Target number of calls.
`targetConversionRate`	number	Target conversion rate.
`scheduledAt`	string	When the campaign is scheduled to run.
`scheduleStart`	integer	Start of the daily calling window.
`scheduleEnd`	integer	End of the daily calling window.
`timezone`	string	Timezone the schedule is interpreted in.
`startDate`	string	Campaign start date.
`endDate`	string	Campaign end date.
`pausedAt`	string	Time the campaign was paused.
`resumedAt`	string	Time the campaign was resumed.
`stoppedAt`	string	Time the campaign stopped.
`cancelledAt`	string	Time the campaign was cancelled.
`meta`	object	Additional campaign metadata.
`createdAt`	string	Creation timestamp.
`updatedAt`	string	Last update timestamp.

When a campaign fails, meta.failure.reason describes why. GET /v1/calls/campaigns/{id} returns these fields plus agentName and a contactGroups array, where each group has an id, name, and type.

Campaign contacts

GET /v1/calls/campaigns/{id}/contacts lists the individual contacts in a campaign.

Field	Type	Description
`phoneNumber`	string	The contact’s phone number.
`status`	string	Call status for this contact.
`attempts`	integer	Number of call attempts made.
`createdAt`	string	Creation timestamp.
`updatedAt`	string	Last update timestamp.

The endpoint accepts page, perPage, and a status filter.

Pagination and filtering

GET /v1/calls/campaigns accepts these query parameters.

Parameter	Type	Description
`page`	integer	Page number.
`perPage`	integer	Items per page.
`status`	string	Filter by status: `active`, `paused`, or `completed`.
`direction`	string	Filter by direction: `inbound` or `outbound`.
`name`	string	Filter by campaign name.
`searchText`	string	Filter campaigns by text.

Both list endpoints return a paged object containing items, page, perPage, totalCount, column, order, and searchText.

Errors

Errors return a code and an error message.

{
  "code": "not_found",
  "error": "campaign not found"
}

Status	Meaning
`400`	The request body or a path parameter is invalid.
`401`	The `X-API-Key` header is missing or invalid.
`403`	The key is not permitted to perform the operation.
`404`	The campaign does not exist.
`422`	The campaign could not be created with the values supplied.

API reference

Agents

Calls

Accounts and workspaces

Billing

Campaign audience

Telephony

Number pools

Knowledge bases

Campaigns

Base URL

Authentication

Endpoints

List campaigns

Create campaign

Get campaign

Update campaign

Delete campaign

List campaign contacts

List campaign conversations

Start campaign

Pause campaign

Resume campaign

Cancel campaign

Before you start

Agent

Phone number

Contact lists

Create a campaign

Control a running campaign

Campaign fields

Campaign contacts

Errors

​Base URL

​Authentication

​Endpoints

List campaigns

Create campaign

Get campaign

Update campaign

Delete campaign

List campaign contacts

List campaign conversations

Start campaign

Pause campaign

Resume campaign

Cancel campaign

​Before you start

Agent

Phone number

Contact lists

​Create a campaign

​Control a running campaign

​Campaign fields

​Campaign contacts

​Pagination and filtering

​Errors

Base URL

Authentication

Endpoints

Before you start

Create a campaign

Control a running campaign

Campaign fields

Campaign contacts

Pagination and filtering

Errors