> ## Documentation Index > Fetch the complete documentation index at: https://docs.useboom.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create initiative > Create a draft initiative or campaign — only a name is required. `isRecurring` decides which: omit it or pass `false` for a campaign (one-time outreach, lives under Campaigns), `true` for an initiative (ongoing work, lives under Initiatives). No UI control changes this afterwards, so set it deliberately. The third kind is a Transactional: pass `transactional` instead (it cannot be combined with `isRecurring: true`). To send ONE message to an audience ONCE, pass `campaign`: its journey is built for you and nobody enrolls on their own. For a WhatsApp send, link an approved template before launching. ## OpenAPI ````yaml /api-reference/openapi.json post /api/v1/initiatives openapi: 3.1.0 info: title: Boom API version: 1.0.0 description: >- Boom's public REST API — one uniform surface over every platform capability. CDP: upsert people and custom objects, define object and relationship types, link and unlink relationships, and record behavioral events — one record per request or up to 1000 per request via the `/batch` endpoints. Segments: read (list, read, membership) and full authoring — discover the filterable catalog, validate a filter, create and update segments, preview match counts, and trigger evaluation. Initiatives: create and configure outreach initiatives, link WhatsApp templates, drive the lifecycle (launch, cancel, archive), and read collected-data summaries. Participants: enroll people into an active initiative, track their status, read conversation transcripts, and stop outreach. Journeys: read-only access to always-on message flows and their metrics. WhatsApp templates: list your WhatsApp numbers and list, read, and create message templates. The same capabilities are exposed as MCP tools with identical schemas. servers: - url: https://www.useboom.ai description: Production - url: https://dev.useboom.ai description: Development (sandbox — use a development organization API key) security: - bearerAuth: [] paths: /api/v1/initiatives: post: tags: - Initiatives summary: Create initiative description: >- Create a draft initiative or campaign — only a name is required. `isRecurring` decides which: omit it or pass `false` for a campaign (one-time outreach, lives under Campaigns), `true` for an initiative (ongoing work, lives under Initiatives). No UI control changes this afterwards, so set it deliberately. The third kind is a Transactional: pass `transactional` instead (it cannot be combined with `isRecurring: true`). To send ONE message to an audience ONCE, pass `campaign`: its journey is built for you and nobody enrolls on their own. For a WhatsApp send, link an approved template before launching. operationId: initiatives_create requestBody: required: true content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: name: type: string minLength: 1 maxLength: 255 description: Initiative name. language: type: string enum: - en - es - pt objective: description: What the initiative aims to learn. type: string maxLength: 2000 context: description: Background the conversation draws on. type: string maxLength: 20000 maxAttempts: description: Outreach attempts per participant. Default 3. type: integer minimum: 1 maximum: 5 isRecurring: description: >- Splits campaigns from initiatives: `false` is a campaign (one-time outreach, listed under Campaigns), `true` is an initiative (ongoing work, listed under Initiatives). A Transactional is a third kind, set with `transactional` on create, and cannot be recurring. A campaign auto-completes once its outreach run finishes; an initiative stays ACTIVE afterward, though no scheduled process currently re-triggers outreach for it. No UI control changes this after creation. Default false. type: boolean flagCondition: description: >- Natural-language condition; conversations matching it get flagged during analysis. Set null to clear. anyOf: - type: string maxLength: 500 - type: 'null' smartSendingMode: description: >- Smart Sending for this initiative's template, SMS and email sends, when the org has a frequency cap. FORCE always sends (and still counts toward the cap); DROP skips a send that would exceed it; DEFER currently behaves as DROP. type: string enum: - DEFER - DROP - FORCE identityDeflection: description: >- Custom reply when a contact asks whether they are talking to a bot. Set null to clear. anyOf: - type: string maxLength: 1000 - type: 'null' guidingQuestions: description: >- The questions the conversation aims to answer. On update this is the complete set, not a patch: omit the field to leave the questions alone, and carry each existing question’s `id` through or it reads as a removal. maxItems: 50 type: array items: type: object properties: id: description: >- Omit to add a new question. On update, pass the id from `initiatives_get` to edit a question in place — a question you drop from a launched initiative is archived if it already has answers (kept for reporting, no longer asked) and deleted otherwise. The id of an archived question is not reusable: sending it creates a new question. type: string questionText: type: string minLength: 1 maxLength: 280 description: The question to cover. answerType: description: >- Defaults to OPEN on a new question. On an existing one, omitting it leaves the type as it is — it does not reset to OPEN. type: string enum: - OPEN - MULTIPLE_CHOICE - BOOLEAN - SCALE priority: description: >- Ask order, 1 first. Defaults to the position in this array. type: integer minimum: 1 maximum: 9007199254740991 scaleMin: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' scaleMax: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' options: description: >- Answer options (MULTIPLE_CHOICE only). On an existing question, omitting them leaves the current options alone; send `[]` to clear them. maxItems: 20 type: array items: type: string minLength: 1 maxLength: 280 required: - questionText channel: default: WHATSAPP description: Default WHATSAPP. type: string enum: - WHATSAPP - EMAIL transactional: description: >- Create a Transactional instead: one event sends this WhatsApp and/or email template: one notification per event, or one per value of `parallelRunsBy` when set. Pass the whole setup here (event, optional key, messages with `templateBindings`/`bindings`) and it is ready in one call; check `initiatives_transactional_get` for anything still missing, then `initiatives_launch`. Change it later with `initiatives_transactional_configure`. Ids: WhatsApp `channelId` from `journeys_message_channels`, WhatsApp `templateId` from `journeys_message_templates` for that channel, email `templateId` from `journeys_email_templates`. Cannot be combined with isRecurring. Any `smartSendingMode` you pass is overridden to FORCE, and `isRecurring` is forced to false. type: object properties: whatsapp: type: object properties: templateId: type: string minLength: 1 channelId: type: string minLength: 1 templateBindings: type: object propertyNames: type: string additionalProperties: type: string description: >- Template variable → where its value comes from: `engagement.workflowState.` for a property of the triggering event, `person.` for a customer field, or `literal:` for fixed text. WhatsApp keys are the placeholder numbers ("1", "2"). required: - templateId - channelId email: type: object properties: templateId: type: string minLength: 1 bindings: type: object propertyNames: type: string additionalProperties: type: string description: >- Template variable → where its value comes from: `engagement.workflowState.` for a property of the triggering event, `person.` for a customer field, or `literal:` for fixed text. WhatsApp keys are the placeholder numbers ("1", "2"). required: - templateId eventName: type: string minLength: 1 pattern: ^[a-zA-Z0-9_]+$ parallelRunsBy: type: string minLength: 1 campaign: description: >- Create a one-time campaign: one email and/or WhatsApp message to an audience, once, at `sendAt`. The audience is a segment snapshot or people you add. Check `initiatives_campaign_get` for anything still missing, then `initiatives_launch` to schedule it. Change it later with `initiatives_campaign_configure`. Never publish a segment-triggered journey for a one-time send: it keeps enrolling people who join the segment later. type: object properties: audience: oneOf: - type: object properties: kind: type: string const: manual required: - kind - type: object properties: kind: type: string const: segment segmentId: type: string minLength: 1 description: The segment id (not its slug). readAtSend: type: boolean description: >- true = read the segment at `sendAt` (someone who leaves it before then drops out); false = read it when the campaign is scheduled. required: - kind - segmentId - readAtSend description: >- 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. sendAt: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ - type: 'null' description: >- ISO instant the message goes out, in the future. Null = as soon as the campaign is scheduled. email: type: object properties: templateId: type: string minLength: 1 bindings: type: object propertyNames: type: string additionalProperties: type: string description: >- Template variable → where its value comes from: `person.` for a customer field (e.g. `person.firstName`), or `literal:` for fixed text. WhatsApp keys are the placeholder numbers ("1", "2"). fromSenderIdOverride: description: >- Sender to send From, with usableAsFrom: true in `journeys_email_templates`. Null = the template sender, else the org default. anyOf: - type: string minLength: 1 - type: 'null' replyToSenderIdOverride: anyOf: - type: string minLength: 1 - type: 'null' required: - templateId description: >- The email message: a PUBLISHED template (`journeys_email_templates`). Unbound variables use the template's own value. whatsapp: type: object properties: templateId: type: string minLength: 1 channelId: type: string minLength: 1 templateBindings: type: object propertyNames: type: string additionalProperties: type: string description: >- Template variable → where its value comes from: `person.` for a customer field (e.g. `person.firstName`), or `literal:` for fixed text. WhatsApp keys are the placeholder numbers ("1", "2"). required: - templateId - channelId description: >- 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. reviewBeforeSending: description: Every send waits in Drafts until someone approves it. type: boolean required: - audience required: - name responses: '201': description: Success content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: id: type: string description: Initiative id. name: type: string channel: type: string enum: - WHATSAPP - EMAIL description: >- Which identifier this initiative reaches people by, derived from its journey: `EMAIL` when the journey only mails, `WHATSAPP` when anything phone-shaped sends. See `sendChannels` for what it actually sends on — this field cannot express SMS or the Meta DMs. sendChannels: type: array items: type: string enum: - WHATSAPP - EMAIL - SMS - INSTAGRAM - FACEBOOK_MESSENGER description: >- Every channel this initiative's journey sends on — the authoritative answer. Empty when it has no journey yet, in which case `channel` falls back to the value stored at creation. status: type: string enum: - DRAFT - ACTIVE - PAUSED - COMPLETED - CANCELED language: type: string description: Conversation language, e.g. `es`. objective: anyOf: - type: string - type: 'null' isRecurring: type: boolean description: >- Splits campaigns from initiatives (a Transactional is the third kind, see `isTransactional`): `false` is a campaign (one-time outreach, listed under Campaigns), `true` is an initiative (ongoing work, listed under Initiatives). A campaign auto-completes once its outreach run finishes; an initiative stays ACTIVE afterward, though no scheduled process currently re-triggers outreach for it. isTransactional: type: boolean description: >- True for a Transactional (one event, one message per channel; listed under Transactional). flagCondition: anyOf: - type: string - type: 'null' description: >- Natural-language condition; matching conversations get flagged during analysis. identityDeflection: anyOf: - type: string - type: 'null' description: >- Custom reply when a contact asks whether they are talking to a bot. smartSendingMode: type: string enum: - DEFER - DROP - FORCE description: 'Smart Sending mode: DEFER, DROP or FORCE.' createdAt: type: string description: ISO 8601 timestamp. updatedAt: type: string description: ISO 8601 timestamp. activatedAt: anyOf: - type: string - type: 'null' completedAt: anyOf: - type: string - type: 'null' canceledAt: anyOf: - type: string - type: 'null' pausedAt: anyOf: - type: string - type: 'null' context: anyOf: - type: string - type: 'null' maxAttempts: type: integer minimum: -9007199254740991 maximum: 9007199254740991 guidingQuestions: type: array items: type: object properties: id: type: string questionText: type: string answerType: type: string priority: type: integer minimum: -9007199254740991 maximum: 9007199254740991 scaleMin: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' scaleMax: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' options: type: array items: type: object properties: id: type: string label: type: string position: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - id - label - position additionalProperties: false required: - id - questionText - answerType - priority - scaleMin - scaleMax - options additionalProperties: false required: - id - name - channel - sendChannels - status - language - objective - isRecurring - isTransactional - flagCondition - identityDeflection - smartSendingMode - createdAt - updatedAt - activatedAt - completedAt - canceledAt - pausedAt - context - maxAttempts - guidingQuestions additionalProperties: false '400': description: Validation failed or the request cannot proceed. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '401': description: Missing, malformed, or revoked API key. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '404': description: The resource does not exist in this organization. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '409': description: >- Conflicts with the current state (duplicates, wrong lifecycle state). content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '422': description: The request is well-formed but semantically invalid. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '429': description: Rate limit exceeded — retry after `Retry-After`. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '500': description: Internal server error. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '503': description: Transient error — retry with a narrower request. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error components: securitySchemes: bearerAuth: type: http scheme: bearer description: 'Organization API key, sent as `Authorization: Bearer boom_org_...`.' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.