Boom Ai Initiatives API
The Initiatives API from Boom Ai — 14 operation(s) for initiatives.
OpenAPI Specification
openapi: 3.1.0
info:
title: Boom CDP Custom Objects Initiatives 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: []
tags:
- name: Initiatives
paths:
/api/v1/initiatives:
get:
operationId: initiatives_list
summary: List initiatives
description: List the organization's initiatives, newest first. Archived initiatives are excluded.
tags:
- Initiatives
parameters:
- name: limit
in: query
required: false
schema:
$schema: https://json-schema.org/draft/2020-12/schema
default: 100
description: Page size.
type: integer
minimum: 1
maximum: 1000
- name: cursor
in: query
required: false
schema:
$schema: https://json-schema.org/draft/2020-12/schema
description: Opaque token from a prior response’s `next_cursor`.
type: string
- name: status
in: query
required: false
schema:
$schema: https://json-schema.org/draft/2020-12/schema
description: 'Comma-separated lifecycle filter, e.g. `DRAFT,ACTIVE`. Allowed: DRAFT, ACTIVE, PAUSED, COMPLETED, CANCELED.'
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
description: Initiative id.
name:
type: string
channel:
type: string
enum:
- WHATSAPP
- EMAIL
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: Whether the initiative keeps processing newly added participants on a schedule.
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.
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'
required:
- id
- name
- channel
- status
- language
- objective
- isRecurring
- flagCondition
- identityDeflection
- createdAt
- updatedAt
- activatedAt
- completedAt
- canceledAt
- pausedAt
additionalProperties: false
next_cursor:
anyOf:
- type: string
- type: 'null'
required:
- data
- next_cursor
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
post:
operationId: initiatives_create
summary: Create initiative
description: Create a draft initiative — only a name is required. For a WhatsApp initiative, link an approved template before launching.
tags:
- Initiatives
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: 5000
maxAttempts:
description: Outreach attempts per participant. Default 3.
type: integer
minimum: 1
maximum: 5
isRecurring:
description: 'Recurring initiative: keeps processing newly added participants on a schedule instead of ending after one pass. 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'
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'
channel:
default: WHATSAPP
description: Default WHATSAPP.
type: string
enum:
- WHATSAPP
- EMAIL
guidingQuestions:
description: The questions the conversation aims to answer.
maxItems: 50
type: array
items:
type: object
properties:
questionText:
type: string
minLength: 1
maxLength: 280
description: The question to cover.
answerType:
description: Default OPEN.
type: string
enum:
- OPEN
- MULTIPLE_CHOICE
- BOOLEAN
- SCALE
priority:
type: integer
minimum: 1
maximum: 5
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).
maxItems: 20
type: array
items:
type: string
minLength: 1
maxLength: 280
required:
- questionText
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
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: Whether the initiative keeps processing newly added participants on a schedule.
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.
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
- status
- language
- objective
- isRecurring
- flagCondition
- identityDeflection
- 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
/api/v1/initiatives/{id}:
get:
operationId: initiatives_get
summary: Get initiative
description: Get one initiative by id.
tags:
- Initiatives
parameters:
- name: id
in: path
required: true
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: string
minLength: 1
description: The initiative id.
responses:
'200':
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
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: Whether the initiative keeps processing newly added participants on a schedule.
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.
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
- status
- language
- objective
- isRecurring
- flagCondition
- identityDeflection
- 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).
messag
# --- truncated at 32 KB (197 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/boom-ai/refs/heads/main/openapi/boom-ai-initiatives-api-openapi.yml