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). 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 patch: operationId: initiatives_update summary: Update initiative description: Edit a draft initiative. Only draft initiatives are editable. 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' 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). 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}/archive: post: operationId: initiatives_archive summary: Archive initiative description: Archive a completed or canceled initiative, hiding it from the default list. Reversible with unarchive. 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: '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}/cancel: post: operationId: initiatives_cancel summary: Cancel initiative description: Cancel an initiative and stop its conversations. Terminal. Requires an org admin. 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: '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}/data/summary: get: operationId: initiatives_summary summary: Data summary description: The initiative's data summary — participant count and, per captured variable, its coverage and rollup. 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: participantCount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 variables: type: array items: type: object properties: key: type: string description: Stable variable key (also used in participant `values`). label: type: string valueKind: type: string cardinality: type: string source: type: string coverage: type: object properties: answered: type: integer minimum: -9007199254740991 maximum: 9007199254740991 eligible: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - answered - eligible additionalProperties: false average: description: Numeric variables only. type: number distribution: description: Categorical variables only. type: array items: type: object properties: value: type: string count: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - value - count additionalProperties: false samples: description: Example answers (text variables only). type: array items: type: string required: - key - label - valueKind - cardinality - source - coverage additionalProperties: false required: - participantCount - variables 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}/extraction-schema: get: operationId: extraction_schema_get summary: Get extraction schema description: Read an initiative's current extraction schema — the typed fields pulled from each conversation. Returns the schema in the exact shape extraction_schema_set accepts, so you can read it, edit it, and set it back. `hasSchema` is false when none is configured yet. 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: initiativeId: type: string hasSchema: type: boolean description: False when the initiative has no extraction schema yet. version: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: The current schema version, or null when none is set. schema: anyOf: - type: object properties: fields: type: object propertyNames: type: string pattern: ^[a-z][a-z0-9_]{0,39}$ additionalProperties: oneOf: - type: object properties: label: type: string minLength: 1 maxLength: 80 description: type: string minLength: 1 maxLength: 500 mapsTo: type: string pattern: ^canonical\.[a-zA-Z][a-zA-Z0-9]*$ type: type: string const: bool required: - label - description - type additionalProperties: false - type: object properties: label: type: string minLength: 1 maxLength: 80 description: type: string minLength: 1 maxLength: 500 mapsTo: type: string pattern: ^canonical\.[a-zA-Z][a-zA-Z0-9]*$ type: type: string const: int min: type: integer minimum: -9007199254740991 maximum: 9007199254740991 max: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - label - description - type additionalProperties: false - type: object properties: label: type: string minLength: 1 maxLength: 80 description: type: string minLength: 1 maxLength: 500 mapsTo: type: string pattern: ^canonical\.[a-zA-Z][a-zA-Z0-9]*$ type: type: string const: enum values: minItems: 1 type: array items: type: string minLength: 1 maxLength: 64 required: - label - description - type - values additionalProperties: false - type: object properties: label: type: string minLength: 1 maxLength: 80 description: type: string minLength: 1 maxLength: 500 mapsTo: type: string pattern: ^canonical\.[a-zA-Z][a-zA-Z0-9]*$ type: type: string const: enum[] values: minItems: 1 type: array items: type: string minLength: 1 maxLength: 64 required: - label - description - type - values additionalProperties: false - type: object properties: label: type: string minLength: 1 maxLength: 80 description: type: string minLength: 1 maxLength: 500 mapsTo: type: string pattern: ^canonical\.[a-zA-Z][a-zA-Z0-9]*$ type: type: string const: string maxLength: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 required: - label - description - type additionalProperties: false - type: object properties: label: type: string minLength: 1 maxLength: 80 description: type: string minLength: 1 maxLength: 500 mapsTo: type: string pattern: ^canonical\.[a-zA-Z][a-zA-Z0-9]*$ type: type: string const: string[] required: - label - description - type additionalProperties: false required: - fields additionalProperties: false - type: 'null' description: The current extraction schema, ready to edit and pass back to extraction_schema_set. Null when none is set. notes: anyOf: - type: string - type: 'null' description: Note on the current version. createdAt: anyOf: - type: string - type: 'null' description: ISO 8601 timestamp of the current version, or null. required: - initiativeId - hasSchema - version - schema - notes - createdAt 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: extraction_schema_set summary: Set extraction schema description: Author or replace an initiative's extraction schema — the typed fields (bool/int/enum/string) pulled from each conversation. Replaces the schema wholesale; submit the complete set of fields, not a diff. A version is created only when the schema actually changes. tags: - Initiatives requestBody: required: true content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: schema: type: object properties: fields: type: object propertyNames: type: string pattern: ^[a-z][a-z0-9_]{0,39}$ additionalProperties: oneOf: - type: object properties: label: type: string minLength: 1 maxLength: 80 description: type: string minLength: 1 maxLength: 500 mapsTo: type: string pattern: ^canonical\.[a-zA-Z][a-zA-Z0-9]*$ type: type: string const: bool required: - label - description - type - type: object properties: label: type: string minLength: 1 maxLength: 80 description: type: string minLength: 1 maxLength: 500 mapsTo: type: string pattern: ^canonical\.[a-zA-Z][a-zA-Z0-9]*$ type: type: string const: int min: type: integer minimum: -9007199254740991 maximum: 9007199254740991 max: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - label - description - type - type: object properties: label: type: string minLength: 1 maxLength: 80 description: type: string minLength: 1 maxLength: 500 mapsTo: type: string pattern: ^canonical\.[a-zA-Z][a-zA-Z0-9]*$ type: type: string const: enum values: minItems: 1 type: array items: type: string minLength: 1 maxLength: 64 required: - label - description - type - values - type: object properties: label: type: string minLength: 1 maxLength: 80 description: type: string minLength: 1 maxLength: 500 mapsTo: type: string pattern: ^canonical\.[a-zA-Z][a-zA-Z0-9]*$ type: type: string const: enum[] values: minItems: 1 type: array items: type: string minLength: 1 maxLength: 64 required: - label - description - type - values - type: object properties: label: type: string minLength: 1 maxLength: 80 description: type: string minLength: 1 maxLength: 500 mapsTo: type: string pattern: ^canonical\.[a-zA-Z][a-zA-Z0-9]*$ type: type: string const: string maxLength: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 required: - label - description - type - type: object properties: label: type: string minLength: 1 maxLength: 80 description: type: string minLength: 1 maxLength: 500 mapsTo: type: string pattern: ^canonical\.[a-zA-Z][a-zA-Z0-9]*$ type: type: string const: string[] required: - label - description - type required: - fields description: 'The complete extraction schema: `{ fields: { : { type, label, description, ... } } }`. Replaces the current schema.' notes: description: Optional note recorded on this schema version. type: string maxLength: 280 required: - schema 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: '201': description: Success content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: initiativeId: type: string version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: The extraction schema version now current for the initiative. Unchanged when the submitted schema was semantically identical to the current one. changed: type: boolean description: Whether a new version was created. False when the submitted schema was semantically identical to the current one — no version bump, and the submitted `notes` were NOT recorded. fieldCount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Number of fields in the schema. notes: anyOf: - type: string - type: 'null' description: The note on the current version — not necessarily the submitted note when `changed` is false. createdAt: type: string description: ISO 8601 timestamp of this version. required: - initiativeId - version - changed - fieldCount - notes - createdAt 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}/launch: post: operationId: initiatives_launch summary: Launch initiative description: Launch a draft initiative — it goes active and Boom starts reaching out. A WhatsApp initiative needs an approved template first. Requires an org admin. 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: '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}/participants: get: operationId: initiatives_participants_list summary: List participants description: List an initiative's participants and the values Boom captured from each, newest first. tags: - Initiatives parameters: - name: id in: path required: true schema: $schema: https://json-schema.org/draft/2020-12/schema type: string minLength: 1 description: Initiative id. - name: limit in: query required: false schema: $schema: https://json-schema.org/draft/2020-12/schema description: Page size, up to 1000. type: integer minimum: 1 maximum: 1000 - name: cursor in: query required: false schema: $schema: https://json-schema.org/draft/2020-12/schema description: Opaque cursor from a previous page. 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: participantId: type: string phoneNumber: anyOf: - type: string - type: 'null' name: anyOf: - type: string - type: 'null' status: type: string enum: - ACTIVE - COMPLETED - STOPPED - EXPIRED - FAILED description: ACTIVE (conversation may still happen), COMPLETED, STOPPED (messaging halted), EXPIRED, or FAILED. messageCount: anyOf: - type: number - type: 'null' createdAt: type: string description: ISO 8601 timestamp. capturedAt: anyOf: - type: string - type: 'null' description: When values were last captured (ISO 8601), if any. values: type: object propertyNames: type: string additionalProperties: type: array items: type: string description: Captured values, keyed by variable key. required: - participantId - phoneNumber - name - status - messageCount - createdAt - capturedAt - values 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_participants_add summary: Add participants description: 'Add people to an active WhatsApp initiative. WARNING: each person added receives a real outbound WhatsApp message. Do-Not-Contact people are skipped.' tags: - Initiatives requestBody: required: true content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: people: minItems: 1 maxItems: 500 type: array items: type: object properties: externalId: type: string minLength: 1 maxLength: 255 description: Stable unique identifier for this person in your system (CDP identity key). phoneNumber: type: string minLength: 1 maxLength: 20 description: Phone number in E.164 format, e.g. +5215512345678 — the WhatsApp recipient. name: description: First name. type: string minLength: 1 maxLength: 255 lastName: description: Last name. type: string minLength: 1 maxLength: 255 context: description: Per-person context values. Keys must match the initiative's context schema. type: object propertyNames: type: string maxLength: 100 additionalProperties: type: string maxLength: 1000 required: - externalId - phoneNumber description: The people to add. Each receives a real WhatsApp message. required: - people parameters: - name: id in: path required: true schema: $schema: https://json-schema.org/draft/2020-12/schema type: string minLength: 1 description: Initiative id. responses: '201': 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: participantId: type: string phoneNumber: type: string status: type: string enum: - ACTIVE - COMPLETED - STOPPED - EXPIRED - FAILED description: ACTIVE (conversation may still happen), COMPLETED, STOPPED (messaging halted), EXPIRED, or FAILED. required: - participantId - phoneNumber - status additionalProperties: false errors: type: array items: type: object properties: index: type: number description: Index of the person in the request `people` array. error: type: object properties: code: type: string description: 'One of: contact_suppressed, invalid_phone_number, unknown_context_key, enrollment_failed.' message: type: string required: - code - message additionalProperties: false required: - index - error additionalProperties: false required: - data - errors 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}/participants/{participantId}: get: operationId: initiatives_participant_get summary: Get participant description: Get one participant's status and captured answers. tags: - Initiatives parameters: - name: id in: path required: true schema: $schema: https://json-schema.org/draft/2020-12/schema type: string minLength: 1 description: Initiative id. - name: participantId in: path required: true schema: $schema: https://json-schema.org/draft/2020-12/schema type: string minLength: 1 description: Participant id, as returned when adding or listing. responses: '200': description: Success content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: participantId: type: string phoneNumber: anyOf: - type: string - type: 'null' name: anyOf: - type: string - type: 'null' status: type: string enum: - ACTIVE - COMPLETED - STOPPED - EXPIRED - FAILED description: ACTIVE (conversation may still happen), COMPLETED, STOPPED (messaging halted), EXPIRED, or FAILED. values: type: array items: type: object properties: label: type: string valueKind: type: string value: type: string sourceQuote: anyOf: - type: string - type: 'null' confidence: anyOf: - type: number - type: 'null' required: - label - valueKind - value - sourceQuote - confidence additionalProperties: false required: - participantId - phoneNumber - name - status - values 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}/participants/{participantId}/messages: get: operationId: initiatives_participant_messages_list summary: Participant messages description: The participant's full conversation transcript for this initiative, in order. tags: - Initiatives parameters: - name: id in: path required: true schema: $schema: https://json-schema.org/draft/2020-12/schema type: string minLength: 1 description: Initiative id. - name: participantId in: path required: true schema: $schema: https://json-schema.org/draft/2020-12/schema type: string minLength: 1 description: Participant id, as returned when adding or listing. responses: '200': description: Success content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: participantId: type: string phoneNumber: anyOf: - type: string - type: 'null' channel: type: string data: type: array items: type: object properties: id: type: string direction: type: string enum: - outbound - inbound author: type: string enum: - agent - participant type: type: string enum: - text - media - template text: type: string mediaUrl: anyOf: - type: string - type: 'null' sentAt: type: string description: ISO 8601 timestamp. required: - id - direction - author - type - text - mediaUrl - sentAt additionalProperties: false next_cursor: type: 'null' required: - participantId - phoneNumber - channel - 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 /api/v1/initiatives/{id}/participants/{participantId}/steps: get: operationId: initiatives_participant_steps_list summary: Participant run steps description: 'The participant''s node-by-node journey run timeline (most recent first): which nodes ran, the routing signal each emitted, and bounded handler output/error. Engine execution history — for what the customer said, use the messages endpoint.' tags: - Initiatives parameters: - name: id in: path required: true schema: $schema: https://json-schema.org/draft/2020-12/schema type: string minLength: 1 description: Initiative id. - name: participantId in: path required: true schema: $schema: https://json-schema.org/draft/2020-12/schema type: string minLength: 1 description: Participant id, as returned when adding or listing. - name: limit in: query required: false schema: $schema: https://json-schema.org/draft/2020-12/schema description: Most-recent steps to return (default 50, max 200). Bounded tail — no older-page cursor; compare against totalSteps. type: integer minimum: 1 maximum: 200 responses: '200': description: Success content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: participantId: type: string totalSteps: type: number description: Full step count, even when more than `limit` were returned. data: type: array items: type: object properties: nodeId: type: string nodeKind: type: string description: The workflow node kind, e.g. HTTP_REQUEST. status: type: string description: RUNNING, COMPLETED, or FAILED. emittedSignal: anyOf: - type: string - type: 'null' description: The routing signal the node emitted, e.g. SUCCESS / FAILED. targetNodeId: anyOf: - type: string - type: 'null' description: The node the emitted signal routed to. enteredAt: type: string description: ISO 8601 timestamp. exitedAt: anyOf: - type: string - type: 'null' description: ISO 8601 timestamp, null if open. output: description: Handler output (bounded); shape depends on node kind. error: anyOf: - type: object properties: name: type: string message: type: string code: anyOf: - type: string - type: number required: - name - message additionalProperties: false - type: 'null' description: Failure detail when the step FAILED (no stack trace). required: - nodeId - nodeKind - status - emittedSignal - targetNodeId - enteredAt - exitedAt - output - error additionalProperties: false next_cursor: type: 'null' required: - participantId - totalSteps - 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 /api/v1/initiatives/{id}/participants/{participantId}/stop: post: operationId: initiatives_participants_stop summary: Stop participant description: Stop all messaging to one participant and close their conversation. Idempotent and safe — it never sends. Their answers and transcript stay readable. tags: - Initiatives parameters: - name: id in: path required: true schema: $schema: https://json-schema.org/draft/2020-12/schema type: string minLength: 1 description: Initiative id. - name: participantId in: path required: true schema: $schema: https://json-schema.org/draft/2020-12/schema type: string minLength: 1 description: Participant id, as returned when adding or listing. responses: '200': description: Success content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: stopped: type: boolean const: true status: type: string enum: - ACTIVE - COMPLETED - STOPPED - EXPIRED - FAILED description: ACTIVE (conversation may still happen), COMPLETED, STOPPED (messaging halted), EXPIRED, or FAILED. required: - stopped - status 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}/templates: get: operationId: initiatives_templates_get summary: Get templates description: List which WhatsApp template each outreach round sends. Round 1 must be linked before a WhatsApp initiative can launch. 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: data: type: array items: type: object properties: round: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Which outreach message this is (1 = the first message). templateId: anyOf: - type: string - type: 'null' description: The linked WhatsApp template, or null if none is linked yet. templateName: anyOf: - type: string - type: 'null' required: - round - templateId - templateName additionalProperties: false required: - data 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_templates_set summary: Set template description: Link an approved WhatsApp template as a round's outreach message. Required before a WhatsApp initiative can launch. tags: - Initiatives requestBody: required: true content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: templateId: type: string minLength: 1 description: An APPROVED WhatsApp template id (from templates_list). round: default: 1 description: Which outreach message (1 = the first). Default 1. type: integer minimum: 1 maximum: 4 required: - templateId 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: '201': description: Success content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: round: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Which outreach message this is (1 = the first message). templateId: anyOf: - type: string - type: 'null' description: The linked WhatsApp template, or null if none is linked yet. templateName: anyOf: - type: string - type: 'null' required: - round - templateId - templateName 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}/unarchive: post: operationId: initiatives_unarchive summary: Unarchive initiative description: Unarchive an initiative, restoring it to the default list. Its status is unchanged. 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: '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 components: securitySchemes: bearerAuth: type: http scheme: bearer description: 'Organization API key, sent as `Authorization: Bearer boom_org_...`.'