Boom Ai CDP People API
The CDP People API from Boom Ai — 4 operation(s) for cdp people.
OpenAPI Specification
openapi: 3.1.0
info:
title: Boom CDP Custom Objects CDP People 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: CDP People
paths:
/api/v1/cdp/people:
get:
operationId: cdp_people_list
summary: List people
description: List the organization's people, newest first.
tags:
- CDP People
parameters:
- name: limit
in: query
required: false
schema:
$schema: https://json-schema.org/draft/2020-12/schema
description: Max items to return, 1-1000 (default 100).
type: integer
minimum: 1
maximum: 1000
- name: cursor
in: query
required: false
schema:
$schema: https://json-schema.org/draft/2020-12/schema
description: Opaque pagination token from a previous response's `next_cursor`. Omit for the first 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:
externalId:
type: string
description: Your stable identifier for this person.
firstName:
anyOf:
- type: string
- type: 'null'
lastName:
anyOf:
- type: string
- type: 'null'
email:
anyOf:
- type: string
- type: 'null'
phoneNumber:
anyOf:
- type: string
- type: 'null'
description: E.164 format.
attributes:
type: object
propertyNames:
type: string
additionalProperties: {}
description: Free-form custom traits.
createdAt:
type: string
description: ISO 8601 timestamp.
updatedAt:
type: string
description: ISO 8601 timestamp.
required:
- externalId
- firstName
- lastName
- email
- phoneNumber
- attributes
- createdAt
- updatedAt
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: cdp_people_upsert
summary: Upsert person
description: Create or update a person by external id. Free-form attributes are fully replaced on each write.
tags:
- CDP People
requestBody:
required: true
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
externalId:
type: string
minLength: 1
maxLength: 255
description: Your stable identifier for this person (idempotency key).
firstName:
description: Given name.
anyOf:
- type: string
maxLength: 255
- type: 'null'
lastName:
description: Family name.
anyOf:
- type: string
maxLength: 255
- type: 'null'
email:
description: Email address.
anyOf:
- type: string
maxLength: 255
- type: 'null'
phoneNumber:
description: Phone number in E.164 format (e.g. +5215555555555).
anyOf:
- type: string
maxLength: 255
- type: 'null'
attributes:
description: Free-form custom traits (full-replace on upsert).
type: object
propertyNames:
type: string
maxLength: 255
additionalProperties: {}
required:
- externalId
responses:
'200':
description: Success
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
externalId:
type: string
created:
type: boolean
required:
- externalId
- created
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/cdp/people/{externalId}:
delete:
operationId: cdp_people_delete
summary: Delete person
description: Soft-delete a person and their outgoing links. Idempotent; behavioral events are kept.
tags:
- CDP People
parameters:
- name: externalId
in: path
required: true
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: string
minLength: 1
maxLength: 255
description: The person externalId.
responses:
'200':
description: Success
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
removed:
type: boolean
required:
- removed
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
get:
operationId: cdp_people_get
summary: Get person
description: Read one person by their external id.
tags:
- CDP People
parameters:
- name: externalId
in: path
required: true
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: string
minLength: 1
maxLength: 255
description: The person externalId.
responses:
'200':
description: Success
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
externalId:
type: string
description: Your stable identifier for this person.
firstName:
anyOf:
- type: string
- type: 'null'
lastName:
anyOf:
- type: string
- type: 'null'
email:
anyOf:
- type: string
- type: 'null'
phoneNumber:
anyOf:
- type: string
- type: 'null'
description: E.164 format.
attributes:
type: object
propertyNames:
type: string
additionalProperties: {}
description: Free-form custom traits.
createdAt:
type: string
description: ISO 8601 timestamp.
updatedAt:
type: string
description: ISO 8601 timestamp.
required:
- externalId
- firstName
- lastName
- email
- phoneNumber
- attributes
- createdAt
- updatedAt
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/cdp/people/batch:
post:
operationId: cdp_people_batch_upsert
summary: Batch upsert people
description: Upsert up to 1000 people in one request. Idempotent and safely retryable.
tags:
- CDP People
requestBody:
required: true
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
items:
minItems: 1
maxItems: 1000
type: array
items:
type: object
properties:
externalId:
type: string
minLength: 1
maxLength: 255
description: Your stable identifier for this person (idempotency key).
firstName:
description: Given name.
anyOf:
- type: string
maxLength: 255
- type: 'null'
lastName:
description: Family name.
anyOf:
- type: string
maxLength: 255
- type: 'null'
email:
description: Email address.
anyOf:
- type: string
maxLength: 255
- type: 'null'
phoneNumber:
description: Phone number in E.164 format (e.g. +5215555555555).
# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/boom-ai/refs/heads/main/openapi/boom-ai-cdp-people-api-openapi.yml