---
title: "Configure campaign"
method: PATCH
path: "/api/v1/initiatives/{id}/campaign"
tags: ["Initiatives"]
---

# Configure campaign

`PATCH /api/v1/initiatives/{id}/campaign`

## Request

- Base URL: `https://www.useboom.ai`
- URL: `https://www.useboom.ai/api/v1/initiatives/{id}/campaign`
- Auth: HTTP bearer

Change a campaign in one call: its audience, send time, messages with variable bindings, or review before sending. Only the fields you pass change (null clears one). The journey is rebuilt for you; a scheduled campaign takes the change immediately. The send time of a scheduled campaign cannot move once people are waiting for it. Returns the setup plus `missing`: what still blocks `initiatives_launch`.

## Path parameters

- `id` string, required: The campaign id.

## Request body

- object
  - `audience` union: Who gets it. `manual`: people you add with `initiatives_participants_add`. `segment`: a one-time snapshot of that segment. It never keeps enrolling people who join later.
    - object
      - `kind` 'manual', required
    - object
      - `kind` 'segment', required
      - `segmentId` string, required: The segment id (not its slug).
      - `readAtSend` boolean, required: true = read the segment at `sendAt` (someone who leaves it before then drops out); false = read it when the campaign is scheduled.
  - `sendAt` string, date-time, nullable: ISO instant the message goes out, in the future. Null = as soon as the campaign is scheduled.
  - `email` object, nullable: The email message: a PUBLISHED template (`journeys_email_templates`). Unbound variables use the template's own value.
    - `templateId` string, required
    - `bindings` object: Template variable → where its value comes from: `person.<field>` for a customer field (e.g. `person.firstName`), or `literal:<text>` for fixed text. WhatsApp keys are the placeholder numbers ("1", "2").
    - `fromSenderIdOverride` string, nullable: Sender to send From, with usableAsFrom: true in `journeys_email_templates`. Null = the template sender, else the org default.
    - `replyToSenderIdOverride` string, nullable
  - `whatsapp` object, nullable: The WhatsApp message: an APPROVED template, the sending number (`journeys_message_channels`), and a binding for EVERY placeholder. Replies go to the agent for 24 hours.
    - `templateId` string, required
    - `channelId` string, required
    - `templateBindings` object: Template variable → where its value comes from: `person.<field>` for a customer field (e.g. `person.firstName`), or `literal:<text>` for fixed text. WhatsApp keys are the placeholder numbers ("1", "2").
  - `reviewBeforeSending` boolean

## Response `200`

Success

- object
  - `id` string, required
  - `formBuilt` boolean, required: False when the one-time initiative was built by hand: it has no campaign setup, edit its journey instead.
  - `sendAt` string, nullable, required
  - `audience` union, required: Who gets it. `manual`: people you add with `initiatives_participants_add`. `segment`: a one-time snapshot of that segment. It never keeps enrolling people who join later.
    - object
      - `kind` 'manual', required
    - object
      - `kind` 'segment', required
      - `segmentId` string, required: The segment id (not its slug).
      - `readAtSend` boolean, required: true = read the segment at `sendAt` (someone who leaves it before then drops out); false = read it when the campaign is scheduled.
  - `audienceCount` number, nullable, required: Segment members right now; null for a manual audience.
  - `audienceMissing` object, nullable, required: Segment members with no email / no phone for WhatsApp.
    - `email` number, required
    - `whatsapp` number, required
  - `whatsapp` object, nullable, required
    - `templateId` string, required
    - `channelId` string, nullable, required
    - `templateBindings` object, required
  - `email` object, nullable, required
    - `templateId` string, required
    - `bindings` object, required
    - `fromSenderIdOverride` string, nullable, required
    - `replyToSenderIdOverride` string, nullable, required
  - `reviewBeforeSending` boolean, required
  - `journeyStatus` 'DRAFT' | 'PUBLISHED' | 'STOPPED', nullable, required
  - `readyToSchedule` boolean, required: True when nothing below blocks `initiatives_launch`.
  - `missing` object[], required: What still blocks scheduling, each with how to fix it.
    - `code` string, required
    - `message` string, required

## Other responses

- `400`: Validation failed or the request cannot proceed.
- `401`: Missing, malformed, or revoked API key.
- `404`: The resource does not exist in this organization.
- `409`: Conflicts with the current state (duplicates, wrong lifecycle state).
- `422`: The request is well-formed but semantically invalid.
- `429`: Rate limit exceeded — retry after `Retry-After`.
- `500`: Internal server error.
- `503`: Transient error — retry with a narrower request.

## Changes

- **2026-11-03** `7c7a773b12ce`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/useboom/apis/boom-api/changes/api/v1/initiatives/:id/campaign/patch.md)

---

[API](https://skmtc.dev/useboom/apis/boom-api.md) - [All operations](https://skmtc.dev/useboom/apis/boom-api/llms.txt) - [OpenAPI document](https://skmtc.dev/useboom/apis/boom-api/revisions/d596d92ed092?raw)