curl --request PATCH \
  --url https://api.topcalls.ai/v1/campaigns/{campaign_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Spring outreach v2"
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "description": "<string>",
  "status": "draft",
  "direction": "outbound",
  "inbound_phone_numbers": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "number": "<string>",
      "label": "<string>"
    }
  ],
  "timezone": "<string>",
  "schedule_time": "2023-11-07T05:31:56Z",
  "dispatch_hours_start": "<string>",
  "dispatch_hours_end": "<string>",
  "dispatch_weekdays": [
    4
  ],
  "dispatch_hours_overrides": {},
  "max_attempts_per_lead": 123,
  "max_parallel_calls": 123,
  "conversion_outcomes": [
    "<string>"
  ],
  "outcome_mapping": [
    "<unknown>"
  ],
  "pause_reason": "<string>",
  "lead_list_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "config": {},
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

{
  "title": "<string>",
  "status": 123,
  "type": "<string>",
  "detail": "<string>",
  "code": "<string>",
  "instance": "<string>",
  "errors": [
    {
      "path": "<string>",
      "message": "<string>",
      "code": "<string>"
    }
  ]
}

{
  "status": 401,
  "title": "Unauthorized",
  "detail": "Invalid API key"
}

{
  "status": 403,
  "title": "Forbidden",
  "detail": "Missing required scope(s): calls:write"
}

{
  "title": "<string>",
  "status": 123,
  "type": "<string>",
  "detail": "<string>",
  "code": "<string>",
  "instance": "<string>",
  "errors": [
    {
      "path": "<string>",
      "message": "<string>",
      "code": "<string>"
    }
  ]
}

{
  "title": "<string>",
  "status": 123,
  "type": "<string>",
  "detail": "<string>",
  "code": "<string>",
  "instance": "<string>",
  "errors": [
    {
      "path": "<string>",
      "message": "<string>",
      "code": "<string>"
    }
  ]
}

{
  "type": "https://api.topcalls.ai/errors/from_number_not_owned",
  "title": "Caller ID Not Allowed",
  "status": 422,
  "code": "from_number_not_owned",
  "detail": "config.from_number must be an active or verified number on your account. Use one of your numbers, or clear from_number and choose numbers with phone_number_ids."
}

Campaigns

Update a campaign

Changes only the fields you send. status can’t be set here, and direction changes only in draft. config merges shallowly: a key you send replaces the stored value, null deletes it, and nested objects such as analysis_schema are replaced whole. A key outside CampaignConfig returns 400 (unrecognized_keys), even as null. So does a change that makes a valid config invalid. lead_list_ids and config.knowledge_base_ids replace the attached set ([] detaches all). Config changes reach calls queued after the update, not ones already queued.

PATCH

campaigns

{campaign_id}

curl --request PATCH \
  --url https://api.topcalls.ai/v1/campaigns/{campaign_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Spring outreach v2"
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "description": "<string>",
  "status": "draft",
  "direction": "outbound",
  "inbound_phone_numbers": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "number": "<string>",
      "label": "<string>"
    }
  ],
  "timezone": "<string>",
  "schedule_time": "2023-11-07T05:31:56Z",
  "dispatch_hours_start": "<string>",
  "dispatch_hours_end": "<string>",
  "dispatch_weekdays": [
    4
  ],
  "dispatch_hours_overrides": {},
  "max_attempts_per_lead": 123,
  "max_parallel_calls": 123,
  "conversion_outcomes": [
    "<string>"
  ],
  "outcome_mapping": [
    "<unknown>"
  ],
  "pause_reason": "<string>",
  "lead_list_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "config": {},
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

{
  "title": "<string>",
  "status": 123,
  "type": "<string>",
  "detail": "<string>",
  "code": "<string>",
  "instance": "<string>",
  "errors": [
    {
      "path": "<string>",
      "message": "<string>",
      "code": "<string>"
    }
  ]
}

{
  "status": 401,
  "title": "Unauthorized",
  "detail": "Invalid API key"
}

{
  "status": 403,
  "title": "Forbidden",
  "detail": "Missing required scope(s): calls:write"
}

{
  "title": "<string>",
  "status": 123,
  "type": "<string>",
  "detail": "<string>",
  "code": "<string>",
  "instance": "<string>",
  "errors": [
    {
      "path": "<string>",
      "message": "<string>",
      "code": "<string>"
    }
  ]
}

{
  "title": "<string>",
  "status": 123,
  "type": "<string>",
  "detail": "<string>",
  "code": "<string>",
  "instance": "<string>",
  "errors": [
    {
      "path": "<string>",
      "message": "<string>",
      "code": "<string>"
    }
  ]
}

{
  "type": "https://api.topcalls.ai/errors/from_number_not_owned",
  "title": "Caller ID Not Allowed",
  "status": 422,
  "code": "from_number_not_owned",
  "detail": "config.from_number must be an active or verified number on your account. Use one of your numbers, or clear from_number and choose numbers with phone_number_ids."
}

Authorizations

Authorization

string

header

required

Use Authorization: Bearer tc_live_xxxxx

Headers

Idempotency-Key

string

Makes a retry safe. A 2xx response is stored for 24 hours per account, and a retry with the same key gets it back with Idempotent-Replay: true instead of running again. Errors aren't stored, so a retry after one runs fresh. The key isn't tied to a path or body: use a new key for every different request. A malformed key gets 400.

Required string length: 8 - 255

Pattern: ^[A-Za-z0-9_-]+$

Example:

"a1b2c3d4-e5f6-7890-abcd-ef0123456789"

Path Parameters

campaign_id

string<uuid>

required

Campaign UUID

Body

application/json

Send only the fields you change. An empty body returns 400, and so does status: use start, pause, resume and stop instead. Config changes apply to calls queued after the update. Calls already queued keep the old config.

name

string

Minimum string length: 1

description

string

direction

enum<string>

Changes only while the campaign is draft, otherwise 409 (campaign_not_draft). Switching to outbound returns 409 (campaign_has_inbound_routes) while a phone number still routes inbound calls to it.

Available options:

outbound,

inbound

timezone

string

IANA timezone for the dispatch hours

dispatch_hours_start

string

Local time dialing may begin, HH:MM or HH:MM:SS.

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

dispatch_hours_end

string

Local time dialing stops, HH:MM or HH:MM:SS.

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

dispatch_weekdays

integer[]

Days dialing is allowed, 1 (Monday) to 7 (Sunday).

Required range: 1 <= x <= 7

dispatch_hours_overrides

object

Per-day dispatch windows that replace the default hours, keyed by weekday "1" to "7". An empty array makes that day off.

Show child attributes

max_attempts_per_lead

integer

Required range: x >= 1

max_parallel_calls

integer

Required range: x >= 1

schedule_time

string<date-time> | null

Same rules as on create. Send null to clear the schedule.

lead_list_ids

string<uuid>[]

Replaces the attached lead lists. [] detaches all. An id outside your account returns 400.

config

object

Merged shallowly into the stored config: a sent key replaces its value (nested objects whole), an omitted key stays, null deletes it. A key that isn't a CampaignConfig field returns 400, even as null. The merged result is validated too: {"mode": "live"} returns 400 while the stored config keeps a legacy-only field or a model outside live.llm in GET /v1/models.

Response

Campaign updated

A campaign as list, get, create and update return it. Only list and get include inbound_phone_numbers.

string<uuid>

account_id

string<uuid>

name

string

description

string | null

status

enum<string>

Available options:

draft,

scheduled,

running,

paused,

completed,

failed,

cancelled

direction

enum<string>

outbound campaigns dial their leads. inbound campaigns are never dialled; they answer on a routed number only while running.

Available options:

outbound,

inbound

inbound_phone_numbers

object[]

Your active or verified numbers with inbound routing on and pointed at this campaign. Full inbound settings are on GET /v1/phone-numbers.

Show child attributes

timezone

string | null

IANA timezone for the dispatch hours. schedule_time is always UTC.

schedule_time

string<date-time> | null

dispatch_hours_start

string | null

Daily start of the dispatch window, HH:MM:SS local time.

dispatch_hours_end

string | null

Daily end of the dispatch window, HH:MM:SS local time.

dispatch_weekdays

integer[]

Days dispatch may run. 1 is Monday, 7 is Sunday.

Required range: 1 <= x <= 7

dispatch_hours_overrides

object | null

Windows for specific weekdays, keyed "1" to "7". An empty list makes that day a day off.

max_attempts_per_lead

integer

max_parallel_calls

integer | null

conversion_outcomes

string[] | null

Dispositions that count toward success_count. Set in the dashboard; the API doesn't accept it.

outcome_mapping

Maps raw call outcomes to dispositions. Set in the dashboard. Expect an object, an empty array [] (the default) or null.

pause_reason

string | null

Why the campaign is paused: manual from the pause endpoint, or an automatic reason such as quota_exceeded, payment_failed or phone_number_deleted.

lead_list_ids

string<uuid>[]

Attached lead lists.

config

object

Configuration for every call the campaign places.

created_at

string<date-time>

updated_at

string<date-time> | null

Overview

Calls

Phone Numbers

Lead lists

Leads

Campaigns

Knowledge Bases

Webhooks

Configuration

Account

Update a campaign

Authorizations

Headers

Path Parameters

Body

Response