Skip to content
RelationsAI
Try it uses test keys only. Requests go straight from your browser to https://voice-api.relationsai.com/v1 with a rai_test_ key, which never places a real call. It works once the API is enabled for your workspace (private preview: support@relationsai.com). Your key stays in this tab's memory; live keys are refused.
RelationsAI API
RelationsAI API

Campaigns

Download schema

Call a list of contacts with one agent, with pause, resume and stop.

List campaigns

GET
https://voice-api.relationsai.com/v1
/campaigns
Bearer (rai_test_... or rai_live_...)

Lists campaigns, newest first. Filter by status. Status and progress are refreshed in the background and can be up to a minute behind; a terminal status reached by the run itself (completed, failed) can take longer to appear.

GET /v1/campaigns · Operation ID: listCampaigns

List campaigns › query Parameters

limit
​integer · min: 1 · max: 100

Maximum number of objects to return, from 1 to 100. Defaults to 25.

Default: 25
cursor
​string · minLength: 1 · maxLength: 512

The next_cursor of the previous page. Send it with exactly the same filters as the request that returned it; a changed filter set is 400 invalid_cursor.

created_after
​string · date-time

Only objects created at or after this time (RFC 3339, UTC).

created_before
​string · date-time

Only objects created before this time (RFC 3339, UTC).

status
​string · enum

Only campaigns in this status.

Enum values:
draft
running
paused
stopped
completed
failed
unknown

List campaigns › Responses

A page of campaigns.

A page of campaigns, newest first.
CampaignList
object
​string · const · required

Always list.

Const value: list
has_more
​boolean · required

True when more objects exist after this page.

next_cursor
​string | null · required

Pass as cursor (with the same filters) to fetch the next page. Null on the last page.

​Campaign[] · required

Campaigns on this page.

Create a campaign

POST
https://voice-api.relationsai.com/v1
/campaigns
Bearer (rai_test_... or rai_live_...)

Creates a campaign in draft status. Nothing is dialled until you start it. You can add recipients now (contact_ids) or later with the recipients endpoint, while the campaign is a draft. Recipients are contacts: create them first, for example with the contact upsert.

Do-not-call numbers are left out when a campaign starts and block a resume; there is no API option to include them. A campaign whose screening was switched off in the console is refused by start and resume (409 campaign_dnc_override_enabled).

POST /v1/campaigns · Operation ID: createCampaign

Create a campaign › Headers

Idempotency-Key
​string · minLength: 1 · maxLength: 255 · pattern: ^[\x21-\x7E]+$

Optional. A unique key for this operation, 1 to 255 printable ASCII characters with no spaces (a UUID v4 is ideal). With it, a retry of the same request (same key, same body) returns the stored answer and never runs the action twice; reuse the same key for every retry, it is kept for 24 hours. Without it, every request runs: a retry after a timeout can repeat the action, so check the state with a GET before retrying.

Create a campaign › Request Body

Create a campaign in `draft` status. Nothing is dialled until you start it.
CampaignCreateRequest
name
​string · minLength: 1 · maxLength: 200 · required

Campaign name.

agent_id
​string · pattern: ^agent_[A-Za-z0-9_-]… · required

The agent that makes the calls.

concurrency_limit
​integer · min: 1 · max: 100

Most simultaneous calls. Defaults to 1. Lowered at start to the plan maximum.

Default: 1
​

The spend at which the campaign is paused. When the campaign's spend reaches the cap the campaign is paused. The check runs about every 15 minutes, so spend can exceed the cap by the calls placed in that time. Omit or null for no cap.

contact_ids
​string[] · maxItems: 1000 · unique

Contacts to add as recipients now. You can also add them later, while the campaign is draft.

Create a campaign › Responses

The campaign was created as a draft.

A campaign calls a list of recipients (contacts) with one agent. Lifecycle: `draft` -> start -> `running` <-> `paused` -> `stopped`, or `running` -> `completed` / `failed`. - **start** begins a run. It is allowed from `draft`, `paused`, `stopped`, `completed` and `failed`. From `paused` it abandons the paused run and begins a new one; from `stopped`, `completed` or `failed` it calls the previous run's recipients again, including people already reached. A start of a campaign that was stopped before it ever started calls the recipients added to it. Every start screens recipients against the do-not-call list, consent and the per-number daily limit and leaves blocked ones out. - **pause** (from `running`) stops new calls; calls already connected finish normally. - **resume** (from `paused`) continues the same run. Every remaining recipient is screened again; if any is now blocked, the resume is refused and the campaign stays paused. - **Do-not-call timing.** Recipients are screened when a run starts and when it resumes, not before each call. A number added to the do-not-call list while the campaign is running is still called by that run: pause and resume the campaign (the resume is refused while a remaining recipient is listed) or stop it. - **stop** (from `draft`, `running` or `paused`) ends the campaign; calls already connected finish. - **Edits** (PATCH) are allowed in every status except `running` and take effect at the next start. A resume continues with the settings the run began with. - **Recipients** can be added only while the campaign is `draft`. A campaign whose do-not-call screening was switched off in the console (`dnc_screening` `disabled_in_console`) cannot be started or resumed through the API. A campaign can also be paused automatically, for example when its budget cap is reached, the workspace balance runs out, or the telephony connection drops. `capabilities` says which actions are allowed right now.
Campaign
id
​string · pattern: ^cmp_[A-Za-z0-9_-]{1… · required

Campaign id (cmp_...).

object
​string · const · required

Always campaign.

Const value: campaign
livemode
​boolean · required

true for a live campaign, false for a test-mode campaign.

name
​string · required

Campaign name.

agent_id
​string | null · required

The agent that makes the calls. Null if the agent was deleted; the campaign cannot start until one is set.

status
​string · enum · required

draft (never started), running, paused, stopped, completed (the run finished), failed (the run ended in failure), unknown. Open enum.

Enum values:
draft
running
paused
stopped
completed
failed
unknown
​CampaignCapabilities · required

Which actions the campaign allows in its current status.

concurrency_limit
​integer · min: 1 · required

Most calls the campaign places at the same time. Lowered at start to the plan maximum (limits.campaign_max_concurrency on the workspace). Campaigns created in the console can hold a higher value than the API accepts on a write.

​required

The spend at which the campaign is paused. When the campaign's spend reaches the cap the campaign is paused. The check runs about every 15 minutes, so spend can exceed the cap by the calls placed in that time. Null for no cap.

recipient_count
​integer · min: 0 · required

Before the first start, the recipients added to the campaign. From a start on, the recipients that run calls: recipients left out by compliance screening at that start are not counted.

​CampaignProgress · required

Call counts for the current or latest run. A call is counted in in_progress until it ends, and only then in connected, no_answer or failed. Updated as calls end; can lag by up to a minute.

​object · required

What the current or latest run has cost so far. Always zero in test mode, which never charges.

run_number
​integer · min: 0 · required

How many runs the campaign has had. 0 before the first start.

created_at
​string · date-time · required

When the campaign was created.

dnc_screening
​string · enum

enforced (numbers on the do-not-call list are left out at every start and block a resume) or disabled_in_console (a person switched screening off for this campaign in the console; the API refuses to start or resume it with 409 campaign_dnc_override_enabled). Read-only. Open enum.

Enum values:
enforced
disabled_in_console

Retrieve a campaign

GET
https://voice-api.relationsai.com/v1
/campaigns/{campaign_id}
Bearer (rai_test_... or rai_live_...)

Returns one campaign with its status, allowed actions (capabilities), progress and spend. The ETag header is the version to send as If-Match when you update it.

GET /v1/campaigns/{campaign_id} · Operation ID: getCampaign

Retrieve a campaign › path Parameters

campaign_id
​string · pattern: ^cmp_[A-Za-z0-9_-]{1… · required

The campaign id (cmp_...).

Retrieve a campaign › Responses

The campaign.

A campaign calls a list of recipients (contacts) with one agent. Lifecycle: `draft` -> start -> `running` <-> `paused` -> `stopped`, or `running` -> `completed` / `failed`. - **start** begins a run. It is allowed from `draft`, `paused`, `stopped`, `completed` and `failed`. From `paused` it abandons the paused run and begins a new one; from `stopped`, `completed` or `failed` it calls the previous run's recipients again, including people already reached. A start of a campaign that was stopped before it ever started calls the recipients added to it. Every start screens recipients against the do-not-call list, consent and the per-number daily limit and leaves blocked ones out. - **pause** (from `running`) stops new calls; calls already connected finish normally. - **resume** (from `paused`) continues the same run. Every remaining recipient is screened again; if any is now blocked, the resume is refused and the campaign stays paused. - **Do-not-call timing.** Recipients are screened when a run starts and when it resumes, not before each call. A number added to the do-not-call list while the campaign is running is still called by that run: pause and resume the campaign (the resume is refused while a remaining recipient is listed) or stop it. - **stop** (from `draft`, `running` or `paused`) ends the campaign; calls already connected finish. - **Edits** (PATCH) are allowed in every status except `running` and take effect at the next start. A resume continues with the settings the run began with. - **Recipients** can be added only while the campaign is `draft`. A campaign whose do-not-call screening was switched off in the console (`dnc_screening` `disabled_in_console`) cannot be started or resumed through the API. A campaign can also be paused automatically, for example when its budget cap is reached, the workspace balance runs out, or the telephony connection drops. `capabilities` says which actions are allowed right now.
Campaign
id
​string · pattern: ^cmp_[A-Za-z0-9_-]{1… · required

Campaign id (cmp_...).

object
​string · const · required

Always campaign.

Const value: campaign
livemode
​boolean · required

true for a live campaign, false for a test-mode campaign.

name
​string · required

Campaign name.

agent_id
​string | null · required

The agent that makes the calls. Null if the agent was deleted; the campaign cannot start until one is set.

status
​string · enum · required

draft (never started), running, paused, stopped, completed (the run finished), failed (the run ended in failure), unknown. Open enum.

Enum values:
draft
running
paused
stopped
completed
failed
unknown
​CampaignCapabilities · required

Which actions the campaign allows in its current status.

concurrency_limit
​integer · min: 1 · required

Most calls the campaign places at the same time. Lowered at start to the plan maximum (limits.campaign_max_concurrency on the workspace). Campaigns created in the console can hold a higher value than the API accepts on a write.

​required

The spend at which the campaign is paused. When the campaign's spend reaches the cap the campaign is paused. The check runs about every 15 minutes, so spend can exceed the cap by the calls placed in that time. Null for no cap.

recipient_count
​integer · min: 0 · required

Before the first start, the recipients added to the campaign. From a start on, the recipients that run calls: recipients left out by compliance screening at that start are not counted.

​CampaignProgress · required

Call counts for the current or latest run. A call is counted in in_progress until it ends, and only then in connected, no_answer or failed. Updated as calls end; can lag by up to a minute.

​object · required

What the current or latest run has cost so far. Always zero in test mode, which never charges.

run_number
​integer · min: 0 · required

How many runs the campaign has had. 0 before the first start.

created_at
​string · date-time · required

When the campaign was created.

dnc_screening
​string · enum

enforced (numbers on the do-not-call list are left out at every start and block a resume) or disabled_in_console (a person switched screening off for this campaign in the console; the API refuses to start or resume it with 409 campaign_dnc_override_enabled). Read-only. Open enum.

Enum values:
enforced
disabled_in_console

Update a campaign

PATCH
https://voice-api.relationsai.com/v1
/campaigns/{campaign_id}
Bearer (rai_test_... or rai_live_...)

Changes a campaign's name, agent, concurrency or budget cap. Allowed in every status except running (pause it first). Changes take effect at the next start: a resume continues the paused run with the settings it began with. Requires If-Match with the campaign's current ETag.

PATCH /v1/campaigns/{campaign_id} · Operation ID: updateCampaign

Update a campaign › path Parameters

campaign_id
​string · pattern: ^cmp_[A-Za-z0-9_-]{1… · required

The campaign id (cmp_...).

Update a campaign › Headers

If-Match
​string · minLength: 1 · maxLength: 128 · required

The ETag from your most recent read of this resource. The update is refused if the resource has changed since. * matches any current version: the update is applied without the concurrency check.

Update a campaign › Request Body

Fields to change. Omitted fields are left as they are. Changes apply from the next start.
CampaignUpdateRequest
name
​string · minLength: 1 · maxLength: 200

Campaign name.

agent_id
​string · pattern: ^agent_[A-Za-z0-9_-]…

The agent that makes the calls.

concurrency_limit
​integer · min: 1 · max: 100

Most simultaneous calls.

​

The spend at which the campaign is paused, or null to remove the cap. When the campaign's spend reaches the cap the campaign is paused. The check runs about every 15 minutes, so spend can exceed the cap by the calls placed in that time.

Update a campaign › Responses

The updated campaign, with its new ETag.

A campaign calls a list of recipients (contacts) with one agent. Lifecycle: `draft` -> start -> `running` <-> `paused` -> `stopped`, or `running` -> `completed` / `failed`. - **start** begins a run. It is allowed from `draft`, `paused`, `stopped`, `completed` and `failed`. From `paused` it abandons the paused run and begins a new one; from `stopped`, `completed` or `failed` it calls the previous run's recipients again, including people already reached. A start of a campaign that was stopped before it ever started calls the recipients added to it. Every start screens recipients against the do-not-call list, consent and the per-number daily limit and leaves blocked ones out. - **pause** (from `running`) stops new calls; calls already connected finish normally. - **resume** (from `paused`) continues the same run. Every remaining recipient is screened again; if any is now blocked, the resume is refused and the campaign stays paused. - **Do-not-call timing.** Recipients are screened when a run starts and when it resumes, not before each call. A number added to the do-not-call list while the campaign is running is still called by that run: pause and resume the campaign (the resume is refused while a remaining recipient is listed) or stop it. - **stop** (from `draft`, `running` or `paused`) ends the campaign; calls already connected finish. - **Edits** (PATCH) are allowed in every status except `running` and take effect at the next start. A resume continues with the settings the run began with. - **Recipients** can be added only while the campaign is `draft`. A campaign whose do-not-call screening was switched off in the console (`dnc_screening` `disabled_in_console`) cannot be started or resumed through the API. A campaign can also be paused automatically, for example when its budget cap is reached, the workspace balance runs out, or the telephony connection drops. `capabilities` says which actions are allowed right now.
Campaign
id
​string · pattern: ^cmp_[A-Za-z0-9_-]{1… · required

Campaign id (cmp_...).

object
​string · const · required

Always campaign.

Const value: campaign
livemode
​boolean · required

true for a live campaign, false for a test-mode campaign.

name
​string · required

Campaign name.

agent_id
​string | null · required

The agent that makes the calls. Null if the agent was deleted; the campaign cannot start until one is set.

status
​string · enum · required

draft (never started), running, paused, stopped, completed (the run finished), failed (the run ended in failure), unknown. Open enum.

Enum values:
draft
running
paused
stopped
completed
failed
unknown
​CampaignCapabilities · required

Which actions the campaign allows in its current status.

concurrency_limit
​integer · min: 1 · required

Most calls the campaign places at the same time. Lowered at start to the plan maximum (limits.campaign_max_concurrency on the workspace). Campaigns created in the console can hold a higher value than the API accepts on a write.

​required

The spend at which the campaign is paused. When the campaign's spend reaches the cap the campaign is paused. The check runs about every 15 minutes, so spend can exceed the cap by the calls placed in that time. Null for no cap.

recipient_count
​integer · min: 0 · required

Before the first start, the recipients added to the campaign. From a start on, the recipients that run calls: recipients left out by compliance screening at that start are not counted.

​CampaignProgress · required

Call counts for the current or latest run. A call is counted in in_progress until it ends, and only then in connected, no_answer or failed. Updated as calls end; can lag by up to a minute.

​object · required

What the current or latest run has cost so far. Always zero in test mode, which never charges.

run_number
​integer · min: 0 · required

How many runs the campaign has had. 0 before the first start.

created_at
​string · date-time · required

When the campaign was created.

dnc_screening
​string · enum

enforced (numbers on the do-not-call list are left out at every start and block a resume) or disabled_in_console (a person switched screening off for this campaign in the console; the API refuses to start or resume it with 409 campaign_dnc_override_enabled). Read-only. Open enum.

Enum values:
enforced
disabled_in_console

List recipients

GET
https://voice-api.relationsai.com/v1
/campaigns/{campaign_id}/recipients
Bearer (rai_test_... or rai_live_...)

Lists a campaign's recipients with what happened to each in the current or latest run: status, attempts, the last call and its outcome, or why the recipient was left out. Recipients are listed in a stable order (not by time). Use the cursor to page; do not rely on the order meaning anything else. Per-recipient results are refreshed in the background and can be up to a minute behind the calls themselves.

GET /v1/campaigns/{campaign_id}/recipients · Operation ID: listCampaignRecipients

List recipients › path Parameters

campaign_id
​string · pattern: ^cmp_[A-Za-z0-9_-]{1… · required

The campaign id (cmp_...).

List recipients › query Parameters

limit
​integer · min: 1 · max: 100

Maximum number of objects to return, from 1 to 100. Defaults to 25.

Default: 25
cursor
​string · minLength: 1 · maxLength: 512

The next_cursor of the previous page. Send it with exactly the same filters as the request that returned it; a changed filter set is 400 invalid_cursor.

status
​string · enum

Only recipients in this status.

Enum values:
pending
in_progress
completed
failed
suppressed
cancelled
unknown

List recipients › Responses

A page of recipients.

A page of campaign recipients, in a stable order.
CampaignRecipientList
object
​string · const · required

Always list.

Const value: list
has_more
​boolean · required

True when more objects exist after this page.

next_cursor
​string | null · required

Pass as cursor (with the same filters) to fetch the next page. Null on the last page.

​CampaignRecipient[] · required

Recipients on this page.

Add recipients

POST
https://voice-api.relationsai.com/v1
/campaigns/{campaign_id}/recipients
Bearer (rai_test_... or rai_live_...)

Adds contacts to a draft campaign. Contacts already in the campaign are skipped. Once a campaign has started, its recipients are fixed: a later start calls the previous run's recipients again. To call a different audience, create a new campaign. Up to 1000 contacts per request and 10,000 per campaign.

POST /v1/campaigns/{campaign_id}/recipients · Operation ID: addCampaignRecipients

Add recipients › path Parameters

campaign_id
​string · pattern: ^cmp_[A-Za-z0-9_-]{1… · required

The campaign id (cmp_...).

Add recipients › Headers

Idempotency-Key
​string · minLength: 1 · maxLength: 255 · pattern: ^[\x21-\x7E]+$

Optional. A unique key for this operation, 1 to 255 printable ASCII characters with no spaces (a UUID v4 is ideal). With it, a retry of the same request (same key, same body) returns the stored answer and never runs the action twice; reuse the same key for every retry, it is kept for 24 hours. Without it, every request runs: a retry after a timeout can repeat the action, so check the state with a GET before retrying.

Add recipients › Request Body

Add contacts to a draft campaign as recipients.
CampaignRecipientsAddRequest
contact_ids
​string[] · minItems: 1 · maxItems: 1000 · unique · required

Contacts to add. Contacts already in the campaign are skipped, not duplicated.

Add recipients › Responses

Recipients were added (or were already present).

Result of adding recipients.
CampaignRecipientsAddResult
object
​string · const · required

Always campaign_recipients_added.

Const value: campaign_recipients_added
livemode
​boolean · required

Mode of the campaign.

campaign_id
​string · required

The campaign.

added
​integer · min: 0 · required

Recipients newly added by this request (contacts already in the campaign are not counted).

recipient_count
​integer · min: 0 · required

Total recipients in the campaign now.

Start a campaign

POST
https://voice-api.relationsai.com/v1
/campaigns/{campaign_id}/start
Bearer (rai_test_... or rai_live_...)

Starts a run: from draft it calls the recipients you added; from stopped, completed or paused it begins a new run with the previous run's recipients (a paused run is abandoned; use resume to continue it instead).

Before anything is dialled the API checks the agent, the account, balance and spend limits, the campaign budget cap, calling hours and the telephony connection, and screens every recipient against the do-not-call list, consent and the per-number daily limit. Blocked recipients are left out (see the recipients list); if that leaves nobody, the start is refused. Screening happens at the start: a number added to the do-not-call list while the run is going is still called by it (pause and resume to re-screen, or stop). A campaign whose do-not-call screening was switched off in the console is refused (409 campaign_dnc_override_enabled).

Daily call limit. In live mode a start counts every recipient of the campaign against the workspace's daily limit of calls placed through the API (see limits.daily_call_limit on the workspace), before anything is dialled, because the run may call each of them. A start that would go past the limit is refused whole with 429 daily_call_limit_reached, and the message says how many calls it needed. A start refused for any other reason before dialling does not count. Test mode has no limit.

What 200 means. The run was started and the campaign is running; calls are placed at up to concurrency_limit at a time. 202 means the start was sent but its confirmation has not arrived yet; the campaign shows running and is reconciled automatically, so retrieve it in a minute rather than starting it again.

POST /v1/campaigns/{campaign_id}/start · Operation ID: startCampaign

Start a campaign › path Parameters

campaign_id
​string · pattern: ^cmp_[A-Za-z0-9_-]{1… · required

The campaign id (cmp_...).

Start a campaign › Headers

Idempotency-Key
​string · minLength: 1 · maxLength: 255 · pattern: ^[\x21-\x7E]+$

Optional. A unique key for this operation, 1 to 255 printable ASCII characters with no spaces (a UUID v4 is ideal). With it, a retry of the same request (same key, same body) returns the stored answer and never runs the action twice; reuse the same key for every retry, it is kept for 24 hours. Without it, every request runs: a retry after a timeout can repeat the action, so check the state with a GET before retrying.

Start a campaign › Responses

The run started.

A campaign calls a list of recipients (contacts) with one agent. Lifecycle: `draft` -> start -> `running` <-> `paused` -> `stopped`, or `running` -> `completed` / `failed`. - **start** begins a run. It is allowed from `draft`, `paused`, `stopped`, `completed` and `failed`. From `paused` it abandons the paused run and begins a new one; from `stopped`, `completed` or `failed` it calls the previous run's recipients again, including people already reached. A start of a campaign that was stopped before it ever started calls the recipients added to it. Every start screens recipients against the do-not-call list, consent and the per-number daily limit and leaves blocked ones out. - **pause** (from `running`) stops new calls; calls already connected finish normally. - **resume** (from `paused`) continues the same run. Every remaining recipient is screened again; if any is now blocked, the resume is refused and the campaign stays paused. - **Do-not-call timing.** Recipients are screened when a run starts and when it resumes, not before each call. A number added to the do-not-call list while the campaign is running is still called by that run: pause and resume the campaign (the resume is refused while a remaining recipient is listed) or stop it. - **stop** (from `draft`, `running` or `paused`) ends the campaign; calls already connected finish. - **Edits** (PATCH) are allowed in every status except `running` and take effect at the next start. A resume continues with the settings the run began with. - **Recipients** can be added only while the campaign is `draft`. A campaign whose do-not-call screening was switched off in the console (`dnc_screening` `disabled_in_console`) cannot be started or resumed through the API. A campaign can also be paused automatically, for example when its budget cap is reached, the workspace balance runs out, or the telephony connection drops. `capabilities` says which actions are allowed right now.
Campaign
id
​string · pattern: ^cmp_[A-Za-z0-9_-]{1… · required

Campaign id (cmp_...).

object
​string · const · required

Always campaign.

Const value: campaign
livemode
​boolean · required

true for a live campaign, false for a test-mode campaign.

name
​string · required

Campaign name.

agent_id
​string | null · required

The agent that makes the calls. Null if the agent was deleted; the campaign cannot start until one is set.

status
​string · enum · required

draft (never started), running, paused, stopped, completed (the run finished), failed (the run ended in failure), unknown. Open enum.

Enum values:
draft
running
paused
stopped
completed
failed
unknown
​CampaignCapabilities · required

Which actions the campaign allows in its current status.

concurrency_limit
​integer · min: 1 · required

Most calls the campaign places at the same time. Lowered at start to the plan maximum (limits.campaign_max_concurrency on the workspace). Campaigns created in the console can hold a higher value than the API accepts on a write.

​required

The spend at which the campaign is paused. When the campaign's spend reaches the cap the campaign is paused. The check runs about every 15 minutes, so spend can exceed the cap by the calls placed in that time. Null for no cap.

recipient_count
​integer · min: 0 · required

Before the first start, the recipients added to the campaign. From a start on, the recipients that run calls: recipients left out by compliance screening at that start are not counted.

​CampaignProgress · required

Call counts for the current or latest run. A call is counted in in_progress until it ends, and only then in connected, no_answer or failed. Updated as calls end; can lag by up to a minute.

​object · required

What the current or latest run has cost so far. Always zero in test mode, which never charges.

run_number
​integer · min: 0 · required

How many runs the campaign has had. 0 before the first start.

created_at
​string · date-time · required

When the campaign was created.

dnc_screening
​string · enum

enforced (numbers on the do-not-call list are left out at every start and block a resume) or disabled_in_console (a person switched screening off for this campaign in the console; the API refuses to start or resume it with 409 campaign_dnc_override_enabled). Read-only. Open enum.

Enum values:
enforced
disabled_in_console

Pause a campaign

POST
https://voice-api.relationsai.com/v1
/campaigns/{campaign_id}/pause
Bearer (rai_test_... or rai_live_...)

Pauses a running campaign: no new calls are started. Calls already connected finish normally and are charged as usual. The campaign is reported paused only once the pause is confirmed; if it is not confirmed you get 409 campaign_pause_not_confirmed and the campaign may still be dialling.

POST /v1/campaigns/{campaign_id}/pause · Operation ID: pauseCampaign

Pause a campaign › path Parameters

campaign_id
​string · pattern: ^cmp_[A-Za-z0-9_-]{1… · required

The campaign id (cmp_...).

Pause a campaign › Headers

Idempotency-Key
​string · minLength: 1 · maxLength: 255 · pattern: ^[\x21-\x7E]+$

Optional. A unique key for this operation, 1 to 255 printable ASCII characters with no spaces (a UUID v4 is ideal). With it, a retry of the same request (same key, same body) returns the stored answer and never runs the action twice; reuse the same key for every retry, it is kept for 24 hours. Without it, every request runs: a retry after a timeout can repeat the action, so check the state with a GET before retrying.

Pause a campaign › Responses

The campaign is paused.

A campaign calls a list of recipients (contacts) with one agent. Lifecycle: `draft` -> start -> `running` <-> `paused` -> `stopped`, or `running` -> `completed` / `failed`. - **start** begins a run. It is allowed from `draft`, `paused`, `stopped`, `completed` and `failed`. From `paused` it abandons the paused run and begins a new one; from `stopped`, `completed` or `failed` it calls the previous run's recipients again, including people already reached. A start of a campaign that was stopped before it ever started calls the recipients added to it. Every start screens recipients against the do-not-call list, consent and the per-number daily limit and leaves blocked ones out. - **pause** (from `running`) stops new calls; calls already connected finish normally. - **resume** (from `paused`) continues the same run. Every remaining recipient is screened again; if any is now blocked, the resume is refused and the campaign stays paused. - **Do-not-call timing.** Recipients are screened when a run starts and when it resumes, not before each call. A number added to the do-not-call list while the campaign is running is still called by that run: pause and resume the campaign (the resume is refused while a remaining recipient is listed) or stop it. - **stop** (from `draft`, `running` or `paused`) ends the campaign; calls already connected finish. - **Edits** (PATCH) are allowed in every status except `running` and take effect at the next start. A resume continues with the settings the run began with. - **Recipients** can be added only while the campaign is `draft`. A campaign whose do-not-call screening was switched off in the console (`dnc_screening` `disabled_in_console`) cannot be started or resumed through the API. A campaign can also be paused automatically, for example when its budget cap is reached, the workspace balance runs out, or the telephony connection drops. `capabilities` says which actions are allowed right now.
Campaign
id
​string · pattern: ^cmp_[A-Za-z0-9_-]{1… · required

Campaign id (cmp_...).

object
​string · const · required

Always campaign.

Const value: campaign
livemode
​boolean · required

true for a live campaign, false for a test-mode campaign.

name
​string · required

Campaign name.

agent_id
​string | null · required

The agent that makes the calls. Null if the agent was deleted; the campaign cannot start until one is set.

status
​string · enum · required

draft (never started), running, paused, stopped, completed (the run finished), failed (the run ended in failure), unknown. Open enum.

Enum values:
draft
running
paused
stopped
completed
failed
unknown
​CampaignCapabilities · required

Which actions the campaign allows in its current status.

concurrency_limit
​integer · min: 1 · required

Most calls the campaign places at the same time. Lowered at start to the plan maximum (limits.campaign_max_concurrency on the workspace). Campaigns created in the console can hold a higher value than the API accepts on a write.

​required

The spend at which the campaign is paused. When the campaign's spend reaches the cap the campaign is paused. The check runs about every 15 minutes, so spend can exceed the cap by the calls placed in that time. Null for no cap.

recipient_count
​integer · min: 0 · required

Before the first start, the recipients added to the campaign. From a start on, the recipients that run calls: recipients left out by compliance screening at that start are not counted.

​CampaignProgress · required

Call counts for the current or latest run. A call is counted in in_progress until it ends, and only then in connected, no_answer or failed. Updated as calls end; can lag by up to a minute.

​object · required

What the current or latest run has cost so far. Always zero in test mode, which never charges.

run_number
​integer · min: 0 · required

How many runs the campaign has had. 0 before the first start.

created_at
​string · date-time · required

When the campaign was created.

dnc_screening
​string · enum

enforced (numbers on the do-not-call list are left out at every start and block a resume) or disabled_in_console (a person switched screening off for this campaign in the console; the API refuses to start or resume it with 409 campaign_dnc_override_enabled). Read-only. Open enum.

Enum values:
enforced
disabled_in_console

Resume a campaign

POST
https://voice-api.relationsai.com/v1
/campaigns/{campaign_id}/resume
Bearer (rai_test_... or rai_live_...)

Continues a paused campaign's run from where it stopped. Before anything is sent, the API checks the agent, the account, balance and spend limits, the budget cap, calling hours and the telephony connection, and screens every recipient the run could still call against the do-not-call list, consent and the per-number daily limit.

A resume cannot drop recipients from a run. So if any remaining recipient is now blocked (for example added to the do-not-call list after the campaign started), nothing is resumed, the campaign stays paused, and you get 409 campaign_recipients_blocked with the blocked contacts. To continue without them, list the recipients still pending, create a new campaign with those contacts minus the blocked ones, start it, and stop this one (stopping does not hang up calls in progress). Do not stop and start this campaign: a new start calls every recipient of the previous run again, including people already reached, and charges for those calls. If too many recipients remain to re-screen, the resume is refused with 422 campaign_too_large.

A resume continues a run its start already counted against the daily call limit, so it counts nothing again.

POST /v1/campaigns/{campaign_id}/resume · Operation ID: resumeCampaign

Resume a campaign › path Parameters

campaign_id
​string · pattern: ^cmp_[A-Za-z0-9_-]{1… · required

The campaign id (cmp_...).

Resume a campaign › Headers

Idempotency-Key
​string · minLength: 1 · maxLength: 255 · pattern: ^[\x21-\x7E]+$

Optional. A unique key for this operation, 1 to 255 printable ASCII characters with no spaces (a UUID v4 is ideal). With it, a retry of the same request (same key, same body) returns the stored answer and never runs the action twice; reuse the same key for every retry, it is kept for 24 hours. Without it, every request runs: a retry after a timeout can repeat the action, so check the state with a GET before retrying.

Resume a campaign › Responses

The run resumed and the campaign is running.

A campaign calls a list of recipients (contacts) with one agent. Lifecycle: `draft` -> start -> `running` <-> `paused` -> `stopped`, or `running` -> `completed` / `failed`. - **start** begins a run. It is allowed from `draft`, `paused`, `stopped`, `completed` and `failed`. From `paused` it abandons the paused run and begins a new one; from `stopped`, `completed` or `failed` it calls the previous run's recipients again, including people already reached. A start of a campaign that was stopped before it ever started calls the recipients added to it. Every start screens recipients against the do-not-call list, consent and the per-number daily limit and leaves blocked ones out. - **pause** (from `running`) stops new calls; calls already connected finish normally. - **resume** (from `paused`) continues the same run. Every remaining recipient is screened again; if any is now blocked, the resume is refused and the campaign stays paused. - **Do-not-call timing.** Recipients are screened when a run starts and when it resumes, not before each call. A number added to the do-not-call list while the campaign is running is still called by that run: pause and resume the campaign (the resume is refused while a remaining recipient is listed) or stop it. - **stop** (from `draft`, `running` or `paused`) ends the campaign; calls already connected finish. - **Edits** (PATCH) are allowed in every status except `running` and take effect at the next start. A resume continues with the settings the run began with. - **Recipients** can be added only while the campaign is `draft`. A campaign whose do-not-call screening was switched off in the console (`dnc_screening` `disabled_in_console`) cannot be started or resumed through the API. A campaign can also be paused automatically, for example when its budget cap is reached, the workspace balance runs out, or the telephony connection drops. `capabilities` says which actions are allowed right now.
Campaign
id
​string · pattern: ^cmp_[A-Za-z0-9_-]{1… · required

Campaign id (cmp_...).

object
​string · const · required

Always campaign.

Const value: campaign
livemode
​boolean · required

true for a live campaign, false for a test-mode campaign.

name
​string · required

Campaign name.

agent_id
​string | null · required

The agent that makes the calls. Null if the agent was deleted; the campaign cannot start until one is set.

status
​string · enum · required

draft (never started), running, paused, stopped, completed (the run finished), failed (the run ended in failure), unknown. Open enum.

Enum values:
draft
running
paused
stopped
completed
failed
unknown
​CampaignCapabilities · required

Which actions the campaign allows in its current status.

concurrency_limit
​integer · min: 1 · required

Most calls the campaign places at the same time. Lowered at start to the plan maximum (limits.campaign_max_concurrency on the workspace). Campaigns created in the console can hold a higher value than the API accepts on a write.

​required

The spend at which the campaign is paused. When the campaign's spend reaches the cap the campaign is paused. The check runs about every 15 minutes, so spend can exceed the cap by the calls placed in that time. Null for no cap.

recipient_count
​integer · min: 0 · required

Before the first start, the recipients added to the campaign. From a start on, the recipients that run calls: recipients left out by compliance screening at that start are not counted.

​CampaignProgress · required

Call counts for the current or latest run. A call is counted in in_progress until it ends, and only then in connected, no_answer or failed. Updated as calls end; can lag by up to a minute.

​object · required

What the current or latest run has cost so far. Always zero in test mode, which never charges.

run_number
​integer · min: 0 · required

How many runs the campaign has had. 0 before the first start.

created_at
​string · date-time · required

When the campaign was created.

dnc_screening
​string · enum

enforced (numbers on the do-not-call list are left out at every start and block a resume) or disabled_in_console (a person switched screening off for this campaign in the console; the API refuses to start or resume it with 409 campaign_dnc_override_enabled). Read-only. Open enum.

Enum values:
enforced
disabled_in_console

Stop a campaign

POST
https://voice-api.relationsai.com/v1
/campaigns/{campaign_id}/stop
Bearer (rai_test_... or rai_live_...)

Stops a draft, running or paused campaign. No further calls are started; calls already connected finish normally. A stopped campaign can be started again, which begins a new run with the same recipients.

POST /v1/campaigns/{campaign_id}/stop · Operation ID: stopCampaign

Stop a campaign › path Parameters

campaign_id
​string · pattern: ^cmp_[A-Za-z0-9_-]{1… · required

The campaign id (cmp_...).

Stop a campaign › Headers

Idempotency-Key
​string · minLength: 1 · maxLength: 255 · pattern: ^[\x21-\x7E]+$

Optional. A unique key for this operation, 1 to 255 printable ASCII characters with no spaces (a UUID v4 is ideal). With it, a retry of the same request (same key, same body) returns the stored answer and never runs the action twice; reuse the same key for every retry, it is kept for 24 hours. Without it, every request runs: a retry after a timeout can repeat the action, so check the state with a GET before retrying.

Stop a campaign › Responses

The campaign is stopped.

A campaign calls a list of recipients (contacts) with one agent. Lifecycle: `draft` -> start -> `running` <-> `paused` -> `stopped`, or `running` -> `completed` / `failed`. - **start** begins a run. It is allowed from `draft`, `paused`, `stopped`, `completed` and `failed`. From `paused` it abandons the paused run and begins a new one; from `stopped`, `completed` or `failed` it calls the previous run's recipients again, including people already reached. A start of a campaign that was stopped before it ever started calls the recipients added to it. Every start screens recipients against the do-not-call list, consent and the per-number daily limit and leaves blocked ones out. - **pause** (from `running`) stops new calls; calls already connected finish normally. - **resume** (from `paused`) continues the same run. Every remaining recipient is screened again; if any is now blocked, the resume is refused and the campaign stays paused. - **Do-not-call timing.** Recipients are screened when a run starts and when it resumes, not before each call. A number added to the do-not-call list while the campaign is running is still called by that run: pause and resume the campaign (the resume is refused while a remaining recipient is listed) or stop it. - **stop** (from `draft`, `running` or `paused`) ends the campaign; calls already connected finish. - **Edits** (PATCH) are allowed in every status except `running` and take effect at the next start. A resume continues with the settings the run began with. - **Recipients** can be added only while the campaign is `draft`. A campaign whose do-not-call screening was switched off in the console (`dnc_screening` `disabled_in_console`) cannot be started or resumed through the API. A campaign can also be paused automatically, for example when its budget cap is reached, the workspace balance runs out, or the telephony connection drops. `capabilities` says which actions are allowed right now.
Campaign
id
​string · pattern: ^cmp_[A-Za-z0-9_-]{1… · required

Campaign id (cmp_...).

object
​string · const · required

Always campaign.

Const value: campaign
livemode
​boolean · required

true for a live campaign, false for a test-mode campaign.

name
​string · required

Campaign name.

agent_id
​string | null · required

The agent that makes the calls. Null if the agent was deleted; the campaign cannot start until one is set.

status
​string · enum · required

draft (never started), running, paused, stopped, completed (the run finished), failed (the run ended in failure), unknown. Open enum.

Enum values:
draft
running
paused
stopped
completed
failed
unknown
​CampaignCapabilities · required

Which actions the campaign allows in its current status.

concurrency_limit
​integer · min: 1 · required

Most calls the campaign places at the same time. Lowered at start to the plan maximum (limits.campaign_max_concurrency on the workspace). Campaigns created in the console can hold a higher value than the API accepts on a write.

​required

The spend at which the campaign is paused. When the campaign's spend reaches the cap the campaign is paused. The check runs about every 15 minutes, so spend can exceed the cap by the calls placed in that time. Null for no cap.

recipient_count
​integer · min: 0 · required

Before the first start, the recipients added to the campaign. From a start on, the recipients that run calls: recipients left out by compliance screening at that start are not counted.

​CampaignProgress · required

Call counts for the current or latest run. A call is counted in in_progress until it ends, and only then in connected, no_answer or failed. Updated as calls end; can lag by up to a minute.

​object · required

What the current or latest run has cost so far. Always zero in test mode, which never charges.

run_number
​integer · min: 0 · required

How many runs the campaign has had. 0 before the first start.

created_at
​string · date-time · required

When the campaign was created.

dnc_screening
​string · enum

enforced (numbers on the do-not-call list are left out at every start and block a resume) or disabled_in_console (a person switched screening off for this campaign in the console; the API refuses to start or resume it with 409 campaign_dnc_override_enabled). Read-only. Open enum.

Enum values:
enforced
disabled_in_console
CallsTranscripts