curl --request POST \
  --url https://api.callers.ai/campaigns \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Customer follow-up calls",
  "voiceId": "507f1f77bcf86cd799439011"
}
'

{
  "status": "success",
  "data": {
    "id": "<string>",
    "name": "<string>",
    "active": true,
    "firstInteractionAt": "<string>",
    "completedAt": "<string>",
    "callParams": {
      "phonesFrom": [
        "<string>"
      ],
      "timezone": "<string>",
      "daysOfWeek": [
        "<string>"
      ],
      "language": "<string>",
      "approvedCountries": [
        "<string>"
      ]
    },
    "organizationId": "<string>",
    "webhooks": [
      "<string>"
    ],
    "slackUrl": "<string>",
    "isIncoming": true,
    "variables": [
      "<string>"
    ],
    "pauseNewChats": true,
    "emailParams": {
      "outboundConnectionIds": [
        "<string>"
      ],
      "inboundConnectionIds": [
        "<string>"
      ],
      "followUpSteps": [
        {
          "delayValue": 123,
          "body": "<string>",
          "prompt": "<string>"
        }
      ],
      "followUpRespectSchedule": true,
      "followUpOnlyIfNoReply": true,
      "fallbackEnabled": true,
      "retryFollowUp": true,
      "signature": "<string>",
      "signatureName": "<string>",
      "defaultSubject": "<string>",
      "timezone": "<string>"
    },
    "incomingPhoneNumber": "<string>",
    "campaignGroupId": "<string>",
    "campaignGroupName": "<string>"
  }
}

{
  "status": "error",
  "message": "<string>",
  "data": [
    {}
  ]
}

{
  "status": "error",
  "message": "<string>"
}

{
  "status": "error",
  "message": "<string>"
}

{
  "status": "error",
  "message": "<string>"
}

Campaigns

Create a campaign

Creates a campaign with the complete configuration surface available in the UI. Supports CALL, CHAT, EMAIL, and TRIGGER campaigns. Most fields are optional and use canonical shared campaign defaults. For a basic call campaign, only name and voiceId are needed. No voice or phone number is selected automatically; IDs shown in examples are placeholders, not defaults. Use callParams for speech, scheduling, retries, voicemail, recording, and web calls; chatParams and emailParams configure their respective channels. steps or nestedSteps define the script, edges connect graph nodes, and fallbacks define recovery behavior. toolFunctions, triggers, preCallActions, knowledgeBaseIds, guardrailSettings, privacy, DNC, and memory settings are also supported. Arrays use replacement semantics and empty arrays clear values. The convenience fields voiceId and phoneNumbers override callParams.voice and callParams.phonesFrom. Omitted timezones default to UTC for deterministic API behavior; send an IANA timezone when local scheduling is required. Call, chat, and email campaigns are created inactive; trigger campaigns activate immediately. Organization, ownership, audit, lifecycle, generated credentials, and provider-managed fields are derived by the server.

POST

campaigns

curl --request POST \
  --url https://api.callers.ai/campaigns \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Customer follow-up calls",
  "voiceId": "507f1f77bcf86cd799439011"
}
'

{
  "status": "success",
  "data": {
    "id": "<string>",
    "name": "<string>",
    "active": true,
    "firstInteractionAt": "<string>",
    "completedAt": "<string>",
    "callParams": {
      "phonesFrom": [
        "<string>"
      ],
      "timezone": "<string>",
      "daysOfWeek": [
        "<string>"
      ],
      "language": "<string>",
      "approvedCountries": [
        "<string>"
      ]
    },
    "organizationId": "<string>",
    "webhooks": [
      "<string>"
    ],
    "slackUrl": "<string>",
    "isIncoming": true,
    "variables": [
      "<string>"
    ],
    "pauseNewChats": true,
    "emailParams": {
      "outboundConnectionIds": [
        "<string>"
      ],
      "inboundConnectionIds": [
        "<string>"
      ],
      "followUpSteps": [
        {
          "delayValue": 123,
          "body": "<string>",
          "prompt": "<string>"
        }
      ],
      "followUpRespectSchedule": true,
      "followUpOnlyIfNoReply": true,
      "fallbackEnabled": true,
      "retryFollowUp": true,
      "signature": "<string>",
      "signatureName": "<string>",
      "defaultSubject": "<string>",
      "timezone": "<string>"
    },
    "incomingPhoneNumber": "<string>",
    "campaignGroupId": "<string>",
    "campaignGroupName": "<string>"
  }
}

{
  "status": "error",
  "message": "<string>",
  "data": [
    {}
  ]
}

{
  "status": "error",
  "message": "<string>"
}

{
  "status": "error",
  "message": "<string>"
}

{
  "status": "error",
  "message": "<string>"
}

Authorizations

Authorization

string

header

required

Headers

x-sub-organization-id

string

Optional sub organization ID. Must belong to your main organization API key.

Body

application/json

name

string

required

Human-readable campaign name. Minimum 3 characters.

Minimum string length: 3

useLocalDialing

boolean | null

required

steps

object[]

Legacy flat script steps. Use this or nestedSteps; omitted scripts receive the standard starter step.

Show child attributes

nestedSteps

object[]

Hierarchical script nodes containing prompts, actions, transfers, forms, and meetings.

Show child attributes

edges

object[]

Directed graph edges connecting script and nested-script nodes.

Show child attributes

fallbacks

object[]

Fallback behavior for silence, errors, retries, and unhandled input.

Show child attributes

interestCriteria

string | null

interestCriteriaV2

object | null

Interest classification criteria. Include a non-empty value when defining a custom criterion.

Show child attributes

webhookUrl

string | null

slackUrl

string | null

webhookStatuses

string[]

webhookEvents

string[]

webhooks

object[]

Show child attributes

slackStatuses

string[]

slackEvents

string[]

isIncoming

boolean | null

default:false

Whether interactions are initiated by the customer. Defaults to false.

scriptVariables

string[]

scriptVariablesV2

object[]

Typed script variables. Omit to receive direction-aware defaults.

Show child attributes

maxIncomingSlots

number

default:2

Required range: 1 < x < 20

callParams

object

Call, speech, scheduling, retry, recording, voicemail, web-call, and model settings. Nested fields use the same defaults as the UI.

Show child attributes

chatParams

object | null

Chat channel, sender numbers, cadence, and drop-off configuration.

Show child attributes

emailParams

object | null

Email connections, sender behavior, follow-up cadence, content, and signature configuration.

Show child attributes

maxOutgoingConcurrency

number

default:10

maxOutgoingCallsBatchSize

number

default:2

limitOutgoingConcurrency

boolean

default:true

summaryQuestions

object[]

Post-interaction summary questions. Each question requires a non-empty name; description and options are optional.

Show child attributes

toolFunctions

object[]

Callable HTTP or integration actions available during an interaction. Every function definition and every parameter property must include a non-empty description. External tools require apiData; ActivePieces tools require activePieceData.

Show child attributes

triggers

object[]

Trigger definitions used by trigger and event-driven campaigns.

Show child attributes

preCallActions

object[]

Actions run before an outbound call. ActivePieces actions require their activePieceAction configuration.

Show child attributes

allowContactDuplicates

boolean

default:false

backgroundNoiseId

string | null

knowledgeBaseIds

string[]

Knowledge bases available to the campaign. IDs must belong to the authenticated organization.

campaignGroupId

string | null

Optional campaign group ID from the authenticated organization.

dialingStrategy

enum<string>

default:ROTATE_NUMBERS

Available options:

ROTATE_NUMBERS,

PREFER_LOCAL_NUMBERS,

AUTO_OPTIMIZE

type

enum<string>

default:CALL

Campaign channel: CALL, CHAT, EMAIL, or TRIGGER. Defaults to CALL.

Available options:

CALL,

CHAT,

TRIGGER,

EMAIL

preCallChat

object | null

Show child attributes

useCase

string | null

useLocalDnc

boolean | null

shouldAddToLocalDnc

boolean | null

sensitiveContentRestricted

boolean

default:false

deleteTranscriptsWithSensitiveData

boolean

default:false

deleteRecordingsWithSensitiveData

boolean

default:false

maskSensitiveMessages

boolean

default:false

turnOffContactMemories

boolean

default:false

turnOffContactMemoryContribution

boolean

default:false

turnOffGlobalContactMemories

boolean

default:false

scriptUpdateRules

object[] | null

Show child attributes

ignoredContactVariables

string[]

guardrailSettings

object | null

Show child attributes

voiceId

string

Convenience alias for callParams.voice. When supplied, this value takes precedence.

Pattern: ^[0-9a-fA-F]{24}$

phoneNumbers

string[]

Convenience alias for callParams.phonesFrom. When supplied, this list takes precedence; an empty list clears assigned call numbers.

webCallCredentials

object | null

Show child attributes

Response

Campaign created successfully

status

enum<string>

Available options:

success

data

object

Show child attributes

Campaigns

Contacts

Calls

Webhooks

Campaign Groups

Organizations

Voices

Contact Memory

Background Noises

Create a campaign

Authorizations

Headers

Body

Response