Edit a campaign

PATCH

/v1/campaigns/{campaign_id}

const url = 'https://api.vocapable.com/v1/campaigns/example';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"name":"example","agent_definition_id":"example","agent_version_id":"example","target":{"contact_list_id":"example"},"number_pool_id":"example","telephony_account_id":"example","compliance_profile_id":"example","scrub_run_id":"example","schedule":{"calling_windows":{"additionalProperty":[{"start":"example","end":"example"}]},"start_date":"2026-04-15","end_date":"2026-04-15","paused_dates":["2026-04-15"]},"max_attempts_per_contact":1,"retry_policy":{"backoff_minutes":[1],"retry_dispositions":["completed_goal"]},"voicemail_drop":{"enabled":false},"concurrency_cap":1,"goal":{}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request PATCH \
  --url https://api.vocapable.com/v1/campaigns/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "agent_definition_id": "example", "agent_version_id": "example", "target": { "contact_list_id": "example" }, "number_pool_id": "example", "telephony_account_id": "example", "compliance_profile_id": "example", "scrub_run_id": "example", "schedule": { "calling_windows": { "additionalProperty": [ { "start": "example", "end": "example" } ] }, "start_date": "2026-04-15", "end_date": "2026-04-15", "paused_dates": [ "2026-04-15" ] }, "max_attempts_per_contact": 1, "retry_policy": { "backoff_minutes": [ 1 ], "retry_dispositions": [ "completed_goal" ] }, "voicemail_drop": { "enabled": false }, "concurrency_cap": 1, "goal": {} }'

Authorizations

HTTPBearer

Parameters

Path Parameters

campaign_id

required

Campaign Id

string

Request Body^required

application/json

CampaignUpdateRequest

PATCH: only the fields present are written.

object

name

Any of:

string
null

string

>= 1 characters <= 200 characters

agent_definition_id

Any of:

string
null

string

agent_version_id

Any of:

string
null

string

target

Any of:

CampaignTarget
null

CampaignTarget

V1 campaigns target a contact list; a segment_id target joins at P2.

object

contact_list_id

required

Contact List Id

string

number_pool_id

Any of:

string
null

string

telephony_account_id

Any of:

string
null

string

compliance_profile_id

Any of:

string
null

string

scrub_run_id

Any of:

string
null

string

schedule

Any of:

CampaignSchedule
null

CampaignSchedule

Per-weekday calling windows plus the campaign’s calendar bounds.

Dates, not instants: they bound the campaign in the callee’s local day, and the policy layer intersects the windows with jurisdictional quiet hours - the stricter wins.

object

calling_windows

Calling Windows

object

key

additional properties

Array<object>

CallingWindow

One local-time window on one weekday.

object

start

required

Start

string

/^([01]\d|2[0-3]):[0-5]\d$/

end

required

End

string

/^([01]\d|2[0-3]):[0-5]\d$/

start_date

Any of:

string
null

string format: date

end_date

Any of:

string
null

string format: date

paused_dates

Paused Dates

Array<string>

max_attempts_per_contact

Any of:

integer
null

integer

>= 1 <= 10

retry_policy

Any of:

RetryPolicy
null

RetryPolicy

Disposition-driven backoff: the spacing ladder and the retriable dispositions.

object

backoff_minutes

Backoff Minutes

Array<integer>

retry_dispositions

Retry Dispositions

Array<string>

Allowed values: completed_goal completed_no_goal answered_incomplete voicemail_machine no_answer busy failed opt_out wrong_person_opt_out dnc_hit scrub_blocked blocked_by_policy abandoned_no_slot inbound_unavailable browser_unavailable

voicemail_drop

Any of:

VoicemailDropPolicy
null

VoicemailDropPolicy

Whether this program leaves artificial-voice voicemail (ADR-0023).

One field, and it is an election rather than a configuration: what is said belongs to the pinned agent version, and how many times is not a knob at all. A drop is terminal

the attempt disposes voicemail_machine and never re-enters the retry ladder - so a contact receives at most one message per campaign by construction, not by a counter a caller could raise.

Launching with this enabled additionally requires the executed Cold Outreach & Data Provenance Waiver, and the waiver is re-checked again at the instant of every drop: a campaign runs for days and a waiver version bump re-arms the gate by design.

object

enabled

Enabled

boolean

concurrency_cap

Any of:

integer
null

integer

>= 1

goal

Any of:

object
null

object

key

additional properties

any

Responses

200

Successful Response

application/json

Campaign

One campaign in full, schedule included.

object

required

string

name

required

Name

string

status

required

CampaignStatus

string

Allowed values: draft scrubbing ready running paused completed cancelled

agent_definition_id

required

Agent Definition Id

string

agent_version_id

Any of:

string
null

string

target

required

CampaignTarget

V1 campaigns target a contact list; a segment_id target joins at P2.

object

contact_list_id

required

Contact List Id

string

number_pool_id

required

Number Pool Id

string

telephony_account_id

required

Telephony Account Id

string

compliance_profile_id

Any of:

string
null

string

scrub_run_id

Any of:

string
null

string

max_attempts_per_contact

required

Max Attempts Per Contact

integer

concurrency_cap

Any of:

integer
null

integer

contacts_total

required

Contacts Total

integer

dialed

required

Dialed

integer

connected

required

Connected

integer

completed_goal

required

Completed Goal

integer

created_at

required

Created At

string format: date-time

updated_at

required

Updated At

string format: date-time

retry_policy

required

RetryPolicy

Disposition-driven backoff: the spacing ladder and the retriable dispositions.

object

backoff_minutes

Backoff Minutes

Array<integer>

retry_dispositions

Retry Dispositions

Array<string>

voicemail_drop

VoicemailDropPolicy

Whether this program leaves artificial-voice voicemail (ADR-0023).

One field, and it is an election rather than a configuration: what is said belongs to the pinned agent version, and how many times is not a knob at all. A drop is terminal

the attempt disposes voicemail_machine and never re-enters the retry ladder - so a contact receives at most one message per campaign by construction, not by a counter a caller could raise.

object

enabled

Enabled

boolean

goal

Goal

object

key

additional properties

any

schedule

Any of:

CampaignSchedule
null

CampaignSchedule

Per-weekday calling windows plus the campaign’s calendar bounds.

Dates, not instants: they bound the campaign in the callee’s local day, and the policy layer intersects the windows with jurisdictional quiet hours - the stricter wins.

object

calling_windows

Calling Windows

object

key

additional properties

Array<object>

CallingWindow

One local-time window on one weekday.

object

start

required

Start

string

/^([01]\d|2[0-3]):[0-5]\d$/

end

required

End

string

/^([01]\d|2[0-3]):[0-5]\d$/

start_date

Any of:

string
null

string format: date

end_date

Any of:

string
null

string format: date

paused_dates

Paused Dates

Array<string>

Example

{
  "status": "draft",
  "retry_policy": {
    "retry_dispositions": [
      "completed_goal"
    ]
  },
  "voicemail_drop": {
    "enabled": false
  }
}

422

Validation Error

application/json

HTTPValidationError

object

detail

Detail

Array<object>

ValidationError

object

loc

required

Location

Array

msg

required

Message

string

type

required

Error Type

string

input

Input

ctx

Context

object

Example^generated

{
  "detail": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example",
      "input": "example",
      "ctx": {}
    }
  ]
}

Edit a campaign

Authorizations

Parameters

Path Parameters

Request Bodyrequired

Responses

200

Example

422

Examplegenerated

Request Body^required

Example^generated