Create a campaign

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

{
  "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"
}

{
  "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."
}

POST

campaigns

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

{
  "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"
}

{
  "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"

Body

application/json

A new campaign is always draft. Change its status with start, pause, resume and stop.

name

string

required

Minimum string length: 1

description

string

direction

enum<string>

default:outbound

outbound campaigns dial their lead lists. inbound campaigns never dial: they answer calls on a phone number routed to them with PATCH /v1/phone-numbers/{id}, and need no lead list.

Available options:

outbound,

inbound

timezone

string

IANA timezone for the dispatch hours. Defaults to UTC.

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

UTC time with a Z suffix (an offset returns 400). If it's in the future, start schedules the campaign for then instead of running it now. Inbound campaigns ignore it.

lead_list_ids

string<uuid>[]

Lead lists to attach. An id outside your account returns 400.

config

object

Settings for every call the campaign places. The shared fields behave as on CreateCallRequest. Unknown keys are refused with 400.

Show child attributes

Response

Campaign created

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

Authorizations

Headers

Body

Response