Create a campaign

POST

/v1/campaigns

curl --request POST \
  --url https://api.vocapable.com/v1/campaigns \
  --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": 3, "retry_policy": { "backoff_minutes": [ 1 ], "retry_dispositions": [ "completed_goal" ] }, "voicemail_drop": { "enabled": false }, "concurrency_cap": 1, "goal": {} }'

Authorizations

• HTTPBearer

Parameters

Header Parameters

Idempotency-Key

Any of:

string

string

null

null

Unique key for this request, so a retry replays the original result instead of repeating the work. Stored for 24 hours; a replayed response carries Idempotent-Replay: true. A UUID is the documented shape.

Request Body^required

Media typeapplication/json

CampaignCreateRequest

Create a campaign in draft. The agent version is pinned at launch, not here.

object

name

required

Name

string

>= 1 characters <= 200 characters

agent_definition_id

Any of:

string

string

null

null

agent_version_id

Any of:

string

string

null

null

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

Any of:

string

string

null

null

compliance_profile_id

Any of:

string

string

null

null

scrub_run_id

Any of:

string

string

null

null

schedule

Any of:

CampaignSchedule

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

string format: date

null

null

end_date

Any of:

string

string format: date

null

null

paused_dates

Paused Dates

Array<string>

null

null

max_attempts_per_contact

Max Attempts Per Contact

integer

default: 3 >= 1 <= 10

retry_policy

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

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

integer

>= 1

null

null

goal

Goal

object

key

additional properties

any

Responses

201

Successful Response

Media typeapplication/json

Campaign

One campaign in full, schedule included.

object

id

required

Id

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

string

null

null

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

string

null

null

scrub_run_id

Any of:

string

string

null

null

max_attempts_per_contact

required

Max Attempts Per Contact

integer

concurrency_cap

Any of:

integer

integer

null

null

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>

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

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

goal

Goal

object

key

additional properties

any

schedule

Any of:

CampaignSchedule

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

string format: date

null

null

end_date

Any of:

string

string format: date

null

null

paused_dates

Paused Dates

Array<string>

null

null

Example

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

422

Validation Error

Media typeapplication/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": {}
    }
  ]
}