Skip to content
Campaigns

Update a campaign

PATCH/campaigns/{id}

Update a campaign's name, outbound number, retry configuration (calling hours, retry delay, max attempts) and concurrency cap. Changes are applied to the campaign's calls that have not completed yet. The assistant is fixed at creation; add contacts with POST /campaigns/{id}/rows, and choose when calls go out with POST /campaigns/{id}/launch-calls.

Path parameters

Request body

  • namestring

    Campaign display name

    1 to 255 characters

  • from_phone_numberstringnullable

    The phone number to use for outbound calls. Editable after launch; applied to the campaign's calls that have not completed yet.

  • max_concurrent_callsnumbernullable

    Maximum concurrent calls. Editable after launch.

    ≥ 1

  • call_retry_configobjectnullable

    Override retry configuration (calling hours, retry delay, max attempts). Editable after launch; applied to the campaign's calls that have not completed yet, whose next attempt is re-scheduled under the new configuration. Its max_retry_attempts is only the default for max_attempts in POST /campaigns/{id}/launch-calls.

  • 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"?: {…} }
  • 404Not found in your organization{ "error": string }

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