Skip to content
Campaigns

Create a campaign

POST/campaigns

Create an outbound calling campaign. Every contact becomes a call in the not_launched status: nothing is dialed until POST /campaigns/{id}/launch-calls sends them.

Request body

  • namestringrequired

    Name of the campaign, unique within your organization.

    at least 1 character

  • assistant_idstring (uuid)required

    ID of the assistant that places the calls. It cannot be changed afterwards.

  • contactsarray of objectrequired

    The contacts to call, at least one. A number listed twice is added once.

    at least 1 item

  • from_phone_numberstring

    Caller ID of the campaign's calls: a number of your organization, in E.164 format. A French mobile number (06, 07) cannot be the caller ID of an automated call. Omitted: the assistant's from_phone_number, or else a Revox number chosen for each destination.

  • max_concurrent_callsnumber

    Maximum number of the campaign's calls in progress at the same time. Omitted: only your organization's limit applies.

    ≥ 1

  • call_retry_configobject

    When and how often the campaign's calls are dialed. Omitted: the default configuration, not the assistant's.

  • timezonestringnullable

    IANA timezone of this campaign's calls, in place of its assistant's: calling windows, the agent's date and calendar slots, callbacks and extracted datetimes. Null: the assistant's timezone, followed live. POST /call timezone still overrides it for one call. Replaces the deprecated call_retry_config.timezone.

Response

200
  • campaignCampaign
    • idstring

      Unique ID of the campaign (UUID).

      Example "9b2d7e41-6c3f-4a8e-b5d0-2f7a1c9e4b63"

    • organization_idstring

      ID of the organization that owns the campaign.

    • namestring

      Name of the campaign, unique within the organization.

      Example "November reminders"

    • assistant_idstring

      ID of the assistant that places the campaign's calls. Set at creation, cannot be changed.

    • assistantAssistantoptional

      The assistant that places the campaign's calls, when it still exists.

    • from_phone_numberstringoptionalnullable

      Phone number the campaign's calls are placed from, in E.164 format. Null: the assistant's from_phone_number, or else the organization's default number.

    • max_concurrent_callsnumberoptionalnullable

      Maximum number of the campaign's calls in progress at the same time. Null: no campaign cap, only your organization's limit applies.

    • call_retry_configCallRetryConfigoptionalnullable

      Retry configuration of the campaign's calls (calling windows, allowed days, delay between attempts, max attempts). Null: the default configuration.

    • timezonestringoptionalnullable

      IANA timezone of this campaign's calls. Null: its assistant's timezone, followed live.

    • status"running" | "paused" | "completed"

      Where the campaign stands. A cancelled campaign is flagged by is_cancelled, not by its status.

      "running"

      Active: its launched calls are placed. A campaign is running from its creation on, before any call is launched too.

      "paused"

      No new call is placed until the campaign is resumed (POST /campaigns/{id}/resume).

      "completed"

      Every contact is done. Launching calls again sets it back to running.

    • is_cancelledboolean

      True when the campaign was cancelled: its pending calls were aborted. Launching calls again clears it.

    • row_statsobjectoptional

      Contacts of the campaign counted by dialing state. Each contact counts in one state only, by priority completed > calling > retry > pending > not_launched / failed / skipped.

    • metadata_keysarray of stringoptional

      Every metadata key found on the campaign's calls, sorted. Not returned by the list endpoint GET /campaigns.

    • funnel_statsobjectoptional

      Sales funnel of the campaign, counted in contacts.

    • created_byOrgMemberoptionalnullable

      The user who created the campaign. Null for campaigns created before this was tracked, and when that user was deleted.

    • created_atstring (date-time)

      When the campaign was created (ISO 8601).

    • updated_atstring (date-time)

      When the campaign was last modified (ISO 8601).

Errors

  • 400Invalid request: a field or parameter failed validation{ "message"?: string, "error"?: string, "bodyErrors"?: {…} }
  • 402Not enough credits on the organization{ "error": string, "code": "INSUFFICIENT_BALANCE" }

Error bodies carry an error (or message) string; a 400 adds bodyErrors.issues. See Errors.