# Boom > Boom's public API — REST and MCP over the same capabilities - [Documentation](https://docs.useboom.ai/introduction.md): Bring your customer data into Boom and turn it into AI conversations with your customers. One platform, two matching surfaces: REST and MCP. - [Start here](https://docs.useboom.ai/start-here.md): What Boom is, and which part of this site is yours depending on what you do. - [The Agent](https://docs.useboom.ai/the-agent.md): One agent per organization, briefed by a knowledge base, that improves from the corrections your team gives it. - [Initiatives](https://docs.useboom.ai/initiatives.md): One outreach mission: who you reach, what the agent is trying to accomplish, and what it comes back with. - [Journeys](https://docs.useboom.ai/journeys.md): The versioned workflow behind an initiative. Build it, validate it, and publish it, all over the API. - [Smart Sending](https://docs.useboom.ai/smart-sending.md): Limit how often one person hears from you, across every initiative in your organization. - [Drafts](https://docs.useboom.ai/drafts.md): Hold a journey's sends for a person to review, then approve or reject each one before it reaches the customer. - [Send a campaign](https://docs.useboom.ai/campaigns.md): Send one email or WhatsApp message to a group of people, once, now or at a time you pick. Boom builds the flow for you and closes the campaign when it is done. - [Send transactional messages](https://docs.useboom.ai/transactional-messages.md): Send one WhatsApp or email message every time something happens in your system, like a payment link or an order confirmation. - [How many notifications a customer gets](https://docs.useboom.ai/transactional-sends.md): One per event, or one per value of a field: how a Transactional counts its sends, and what happens when an event arrives twice. - [Inbound conversations](https://docs.useboom.ai/inbound.md): When a customer writes first, the same agent answers, with the same context it uses for outreach. - [Segments](https://docs.useboom.ai/segments.md): Define an audience with a filter, keep it fresh, and use it to trigger outreach. - [Extraction](https://docs.useboom.ai/extraction.md): Define the typed fields a conversation should yield, then read the structured data back. - [Analytics and attribution](https://docs.useboom.ai/analytics.md): Define what success means for an initiative, then measure against it. - [Email open and click tracking](https://docs.useboom.ai/email-tracking.md): Measure who opens your emails and clicks their links, with one DNS record on your sending domain. - [Web widget](https://docs.useboom.ai/web-widget.md): One script tag puts the same agent that answers WhatsApp on your own website. - [Use MCP](https://docs.useboom.ai/use-mcp.md): Connect Boom to Claude, Cursor, or any AI tool. Add one link, sign in: no API key. - [Skills](https://docs.useboom.ai/skills.md): Install Boom's Agent Skills so Claude can run your customer conversations end-to-end over Boom. - [Connect your database](https://docs.useboom.ai/connect-your-database.md): Sync customers into the Boom CDP straight from your own PostgreSQL or MySQL database. - [Webhooks](https://docs.useboom.ai/webhooks.md): Get a POST to your endpoint when a journey run starts, ends, an enrollment is rejected, or a conversation is handed to a human. - [One uniform surface](https://docs.useboom.ai/one-surface.md): Every capability is defined once and exposed identically over REST and MCP: same names, same inputs, same errors. - [Events](https://docs.useboom.ai/events.md): Record behavioral events, then read and list them back. - [Relationship types](https://docs.useboom.ai/relationship-types.md): Register the catalog of link shapes and the data you need to do it correctly. - [Template variables](https://docs.useboom.ai/template-variables.md): How to bind a WhatsApp template's placeholders to live data in a journey. - [Email templates](https://docs.useboom.ai/email-templates.md): Read, create and update email templates over MCP or the API — as builder blocks or as HTML. - [Message logs](https://docs.useboom.ai/message-logs.md): List what your organization sent and what happened to each message — delivered, failed, or blocked — over MCP or the API. - [Customer Data Platform](https://docs.useboom.ai/cdp/overview.md): The REST API for getting customer data into Boom: people, custom objects, events, and the relationships between them. - [List people](https://docs.useboom.ai/api-reference/cdp-people/list-people.md): List the organization's people, newest first. - [Search people](https://docs.useboom.ai/api-reference/cdp-people/search-people.md): Search the organization's people by name, or a partial email / phone / externalId. Returns a relevance-ranked shortlist. - [Get person](https://docs.useboom.ai/api-reference/cdp-people/get-person.md): Read one person by their external id. - [Upsert person](https://docs.useboom.ai/api-reference/cdp-people/upsert-person.md): Create or update a person by external id. Free-form attributes are fully replaced on each write. - [Batch upsert people](https://docs.useboom.ai/api-reference/cdp-people/batch-upsert-people.md): Upsert up to 1000 people in one request. Idempotent and safely retryable. - [Delete person](https://docs.useboom.ai/api-reference/cdp-people/delete-person.md): Soft-delete a person and their outgoing links. Idempotent; behavioral events are kept. - [List objects](https://docs.useboom.ai/api-reference/cdp-custom-objects/list-objects.md): List custom objects of one type, newest first. - [Get object](https://docs.useboom.ai/api-reference/cdp-custom-objects/get-object.md): Read one custom object by type and external id. - [Upsert object](https://docs.useboom.ai/api-reference/cdp-custom-objects/upsert-object.md): Create or update a custom object by type and external id. The type must already exist. By default `attributes` is REPLACED wholesale — pass `mode: 'merge'` to add or change a subset without deleting the rest, and `createMissing: false` to update only when the object already exists. - [Batch upsert objects](https://docs.useboom.ai/api-reference/cdp-custom-objects/batch-upsert-objects.md): Upsert up to 1000 custom objects in one request. Idempotent and safely retryable. By DEFAULT each item REPLACES that object's entire `attributes` blob, so an item carrying only the fields you want to change DELETES every other attribute on that object. To add or change a subset across many objects,… - [Delete object](https://docs.useboom.ai/api-reference/cdp-custom-objects/delete-object.md): Soft-delete a custom object and its links. Idempotent. - [List events](https://docs.useboom.ai/api-reference/cdp-events/list-events.md): List events, newest first, with optional filters by name, subject, and time range. - [Get event](https://docs.useboom.ai/api-reference/cdp-events/get-event.md): Read one event by its external id. - [Record event](https://docs.useboom.ai/api-reference/cdp-events/record-event.md): Record one behavioral event for a person and/or custom object. This is the real-time path — it triggers journey enrollment. Unknown subjects still ingest and are linked later. - [Batch record events](https://docs.useboom.ai/api-reference/cdp-events/batch-record-events.md): Ingest up to 1000 events in one request, for bulk or historical loads. Unlike the single endpoint, this does not trigger journey enrollment. - [List relationships](https://docs.useboom.ai/api-reference/cdp-relationships/list-relationships.md): List relationship edges of one kind, anchored on a person or custom object, newest first. - [Link relationship](https://docs.useboom.ai/api-reference/cdp-relationships/link-relationship.md): Link a person to a custom object, or one custom object to another. Idempotent. - [Unlink relationship](https://docs.useboom.ai/api-reference/cdp-relationships/unlink-relationship.md): Unlink (soft-delete) a relationship. Idempotent. - [Batch link / unlink](https://docs.useboom.ai/api-reference/cdp-relationships/batch-link-unlink.md): Link or unlink up to 1000 relationships in one request. - [List object types](https://docs.useboom.ai/api-reference/cdp-custom-objects/list-object-types.md): List the organization's custom object types. - [Get object type](https://docs.useboom.ai/api-reference/cdp-custom-objects/get-object-type.md): Read one custom object type by name. - [List relationship types](https://docs.useboom.ai/api-reference/cdp-relationships/list-relationship-types.md): List the organization's relationship types — use it to discover valid link shapes before linking. - [Get relationship type](https://docs.useboom.ai/api-reference/cdp-relationships/get-relationship-type.md): Read one relationship type by id. - [Create object type](https://docs.useboom.ai/api-reference/cdp-custom-objects/create-object-type.md): Create a custom object type — required before you can upsert objects of that kind. - [Register relationship type](https://docs.useboom.ai/api-reference/cdp-relationships/register-relationship-type.md): Register a relationship type and its metadata. Re-registering an existing type updates it in place. - [API](https://docs.useboom.ai/api-reference/overview.md): The REST API for acting on your customer data: build audiences, run initiatives, author the flow behind them, and read back what the conversations produced. - [Quickstart](https://docs.useboom.ai/quickstart.md): Create a person, an object type, an object, a relationship type, and a link. - [Authentication](https://docs.useboom.ai/authentication.md): Authenticate with an organization API key. - [Rate limits & errors](https://docs.useboom.ai/rate-limits-and-errors.md): Limits, headers, and the error shape used across all endpoints. - [List initiatives](https://docs.useboom.ai/api-reference/initiatives/list-initiatives.md): List the organization's initiatives and campaigns, newest first. All three kinds are the same record type: `isRecurring` splits campaigns from initiatives, and `isTransactional` selects Transactionals (event-triggered sends, kept out of the other two lists unless you pass it). Archived rows are excl… - [Get initiative](https://docs.useboom.ai/api-reference/initiatives/get-initiative.md): Get one initiative by id. - [Create initiative](https://docs.useboom.ai/api-reference/initiatives/create-initiative.md): Create a draft initiative or campaign — only a name is required. `isRecurring` decides which: omit it or pass `false` for a campaign (one-time outreach, lives under Campaigns), `true` for an initiative (ongoing work, lives under Initiatives). No UI control changes this afterwards, so set it delibera… - [Update initiative](https://docs.useboom.ai/api-reference/initiatives/update-initiative.md): Edit an initiative. A launched one still takes its agent-facing content (name, objective, context, guidingQuestions, flagCondition, identityDeflection) and its smartSendingMode and serves the edit on the next turn; the structural fields are draft-only, and a completed or canceled initiative is froze… - [Launch initiative](https://docs.useboom.ai/api-reference/initiatives/launch-initiative.md): Launch a draft initiative — it goes active and Boom starts reaching out. Its journey is published as part of the launch, on every channel (fails with the journey's issues if it cannot be), so no separate journeys_publish is needed. A WhatsApp initiative also needs an approved template first. Over MC… - [Cancel initiative](https://docs.useboom.ai/api-reference/initiatives/cancel-initiative.md): Cancel an initiative and stop its conversations. Terminal. Over MCP, requires the org:initiatives:launch permission (Owner and Admin roles). - [Pause initiative](https://docs.useboom.ai/api-reference/initiatives/pause-initiative.md): Stop enrolling new people into this initiative. Anyone already enrolled keeps their run, and conversations in progress continue normally. Reversible with resume. - [Resume initiative](https://docs.useboom.ai/api-reference/initiatives/resume-initiative.md): Resume a paused initiative so it starts enrolling people again. - [Archive initiative](https://docs.useboom.ai/api-reference/initiatives/archive-initiative.md): Hide an initiative from the default list. Takes a draft, completed or canceled one — a draft created by mistake does not have to be canceled first — but not a running (active or paused) one. Nothing else about the initiative changes, and unarchive reverses it. - [Unarchive initiative](https://docs.useboom.ai/api-reference/initiatives/unarchive-initiative.md): Restore an archived initiative to the default list. Its status is unchanged, and any archived initiative can be restored regardless of status. - [Get templates](https://docs.useboom.ai/api-reference/initiatives/get-templates.md): List which WhatsApp template each outreach round sends. Round 1 must be linked before a WhatsApp initiative can launch. - [Set template](https://docs.useboom.ai/api-reference/initiatives/set-template.md): Link an approved WhatsApp template as a round's outreach message — round 1 is the opening message. Required before a WhatsApp initiative can launch. This writes the initiative's journey DRAFT: customers keep receiving the previous template until the journey is published. - [Data summary](https://docs.useboom.ai/api-reference/initiatives/data-summary.md): The initiative's data summary — participant count and, per captured variable, its coverage and rollup. - [List success metrics](https://docs.useboom.ai/api-reference/initiatives/list-success-metrics.md): Read the success metrics configured on an initiative — what counts as a win, and how it is measured. Returns them in the exact shape success_metrics_upsert accepts, so you can read one, edit it and send it back. An initiative with no metric configured returns an empty list. Editing a metric changes… - [Success-metric catalog](https://docs.useboom.ai/api-reference/initiatives/success-metric-catalog.md): List everything a success metric can point at on this initiative: the events this organization records, its custom-object types, and the variables extracted from this initiative's conversations. Pass `eventName` to also get that event's properties, or `objectTypeId` to get that type's attributes and… - [Add or replace a success metric](https://docs.useboom.ai/api-reference/initiatives/add-or-replace-a-success-metric.md): Configure what counts as success for an initiative: a customer-data event, a record on a custom object, or a value extracted from the conversation, measured within 48 hours of the first message. Omit `rootId` to add a metric; pass an existing metric's `rootId` to replace it with a new version. This… - [Delete a success metric](https://docs.useboom.ai/api-reference/initiatives/delete-a-success-metric.md): Retire a success metric. It disappears from the dashboard immediately — including from past periods, because successes are recalculated on every read, so the numbers this metric reported for earlier conversations go with it. The configuration is kept for the audit trail and success_metrics_list can… - [Add participants](https://docs.useboom.ai/api-reference/initiatives/add-participants.md): Add people to an active WhatsApp or email initiative. WARNING: each person added receives a real outbound message immediately. Identify each person by `phoneNumber` on a WhatsApp initiative and by `email` on an email one. Requires a published journey (launching publishes it). Do-Not-Contact people a… - [List participants](https://docs.useboom.ai/api-reference/initiatives/list-participants.md): List an initiative's participants and the values Boom captured from each, newest first. Each row carries both contact identifiers (`phoneNumber`, `email`) — on an email initiative the phone is null for everyone, so read the one the initiative actually sends to. Filter by personExternalId to find one… - [Get participant](https://docs.useboom.ai/api-reference/initiatives/get-participant.md): Get one participant's status and captured answers. - [Participant messages](https://docs.useboom.ai/api-reference/initiatives/participant-messages.md): The participant's conversation transcript, in order. Defaults to this initiative only; pass scope="customer" for everything this person ever said to you across initiatives — use that whenever you need to know whether someone answered at all, since a reply lands on whichever initiative was live at th… - [List transcripts](https://docs.useboom.ai/api-reference/initiatives/list-transcripts.md): Full conversation transcripts for a page of participants, newest participant first. Use this to read or export ALL conversations of an initiative — one call per page (up to 100 participants) instead of looping the per-participant messages endpoint. - [Stop participant](https://docs.useboom.ai/api-reference/initiatives/stop-participant.md): End one participant’s run: no further scheduled messages are sent and their session is closed. Idempotent and safe — it never sends. Their answers and transcript stay readable, and the conversation keeps whoever it was assigned to. - [List journeys](https://docs.useboom.ai/api-reference/journeys/list-journeys.md): List the organization's journeys, newest first. A journey is the step sequence people move through, attached to an initiative. Read-only. - [Get journey](https://docs.useboom.ai/api-reference/journeys/get-journey.md): Get one journey by id — its trigger and the ordered steps people move through. Read-only, for inspecting setup. - [Get journey definition](https://docs.useboom.ai/api-reference/journeys/get-journey-definition.md): Get a journey's full editable graph (all nodes, their config, and connections) so it can be modified and saved back. Unlike journeys_get, this is the complete authoring shape, not the sanitized public summary. - [Node catalog](https://docs.useboom.ai/api-reference/journeys/node-catalog.md): Describes every journey node kind — its inputs, its output handles (the signals it can emit), and the rules for connecting nodes. Read this before building or editing a journey. - [Validate journey](https://docs.useboom.ai/api-reference/journeys/validate-journey.md): Dry-run the publish checks against a journey graph without saving. Pass a `journeyId` to validate the stored draft, or a `definition` to validate a graph as sent (exactly one of the two). Returns whether it is valid and the list of issues (errors block publishing; warnings are advisory). Use it to i… - [Create draft](https://docs.useboom.ai/api-reference/journeys/create-draft.md): Create a new draft journey on an initiative from a full graph. The draft is editable and does not run until published (which is done in the app). Omit node positions and the server lays the graph out automatically. - [Update draft](https://docs.useboom.ai/api-reference/journeys/update-draft.md): Replace a draft journey's whole graph. Journey-level metadata is merged, not replaced — keys the payload omits (e.g. the environment pin) keep their stored values. Only drafts can be edited; published versions are frozen (edit a live journey in the app to fork a new draft). Omit node positions and t… - [Add node](https://docs.useboom.ai/api-reference/journeys/add-node.md): Add one node to a draft journey. Positions are optional (auto-laid-out). Wire it up separately with journeys_connect_nodes. - [Update node](https://docs.useboom.ai/api-reference/journeys/update-node.md): Update one node's name, position, and/or config (inputs shallow-merge). Use journeys_authoring_catalog for a node kind's input fields. - [Delete node](https://docs.useboom.ai/api-reference/journeys/delete-node.md): Remove one node and every edge connected to it from a draft journey. - [Connect nodes](https://docs.useboom.ai/api-reference/journeys/connect-nodes.md): Wire an edge from one node to another on a given output handle (the emitted signal, e.g. SENT, REPLIED, YES, case:). A handle can wire to only one node. - [Disconnect nodes](https://docs.useboom.ai/api-reference/journeys/disconnect-nodes.md): Remove edges leaving a node. Narrow by target and/or handle; with neither, all outgoing edges from the node are removed. - [Set trigger](https://docs.useboom.ai/api-reference/journeys/set-trigger.md): Configure how people enter the journey by updating its ENTRY node: manual, segment (needs segmentId), cdp_event (needs eventName), or inbound (needs inboundAction and inboundChannelIds, optionally narrowed to an inboundKeyword), with an optional frequency cap, or an optional parallelRunsBy on cdp_ev… - [Fork journey](https://docs.useboom.ai/api-reference/journeys/fork-journey.md): Copy a PUBLISHED journey into a fresh editable draft. The live version keeps running until the new draft is published. Use this to edit a live journey safely. - [Publish journey](https://docs.useboom.ai/api-reference/journeys/publish-journey.md): Publish a draft journey so it goes live and starts enrolling people (this begins real outreach). Validates first and requires confirm: true. Errors block the publish; any advisory warnings the journey still carries come back in `warnings`. Call it WITHOUT confirm first to preview: nothing is publish… - [Stop journey](https://docs.useboom.ai/api-reference/journeys/stop-journey.md): Retire a live journey: no one else is enrolled, and anyone already enrolled who has not been messaged yet is dropped before their message goes out. Conversations already in progress continue normally. Requires confirm: true. This cannot be undone — re-running the campaign means publishing again. - [List message channels](https://docs.useboom.ai/api-reference/journeys/list-message-channels.md): List the channels a journey send node can send from, across every channel that has one: WhatsApp (SEND_MESSAGE), SMS (SEND_SMS), Instagram (SEND_INSTAGRAM) and Messenger (SEND_MESSENGER). Use a row's id as the node's channelId — `sendNodeKind` says which node kind takes it. Approved templates are a… - [List message templates](https://docs.useboom.ai/api-reference/journeys/list-message-templates.md): List the approved WhatsApp templates a SEND_MESSAGE node can use from a given channel. A template belongs to one channel account, so pass the same channelId you pin on the node. - [List email templates](https://docs.useboom.ai/api-reference/journeys/list-email-templates.md): Everything a SEND_EMAIL node needs: the PUBLISHED email templates it can use, the org's email readiness, and the senders available as From / Reply-To overrides. Email has no channelId — it sends from the org's verified domain — which is why it is not in journeys_message_channels. Publish refuses a S… - [Event catalog](https://docs.useboom.ai/api-reference/journeys/event-catalog.md): List the CDP event names seen for your organization. Use these for a cdp_event trigger, a DISPATCH_EVENT node, or an event-based DECISION condition. - [Condition catalog](https://docs.useboom.ai/api-reference/journeys/condition-catalog.md): List the person attributes and computed attributes available for DECISION and CASE CONDITIONS, plus the custom object types. Attribute tokens are ready to use as condition selection paths (e.g. attributes.plan, computed.ltv). NOTE: these `attributes.*` tokens are ONLY for DECISION/CASE conditions —… - [Message variable catalog](https://docs.useboom.ai/api-reference/journeys/message-variable-catalog.md): List the variables a SEND_MESSAGE template binding can reference for a journey — the same set the builder offers, and the authority on what resolves for THIS journey (when docs and this catalog disagree, trust the catalog). customer.* and person.* are offered for every trigger type (person.* is read… - [List segments](https://docs.useboom.ai/api-reference/segments/list-segments.md): List the organization's active segments, newest first. Archived segments are excluded. - [Get a segment](https://docs.useboom.ai/api-reference/segments/get-a-segment.md): Get one segment by slug, with a live member count. - [List segment members](https://docs.useboom.ai/api-reference/segments/list-segment-members.md): List a segment's active members, newest first. - [Get the segment filter catalog](https://docs.useboom.ai/api-reference/segments/get-the-segment-filter-catalog.md): Everything filterable in your organization — person attributes, related data, computed variables, and the events people can be filtered on — with the token and operators to use for each. Read this first when building a filter. The `events` section is what makes behavioural filters possible: an `even… - [Validate a segment filter](https://docs.useboom.ai/api-reference/segments/validate-a-segment-filter.md): Dry-run a filter expression against your live catalog — nothing is saved. Returns whether it's valid, or the field to fix. - [Create a segment](https://docs.useboom.ai/api-reference/segments/create-a-segment.md): Create a segment from a filter expression. It starts empty until evaluated. Validate and preview the filter first. - [Update a segment](https://docs.useboom.ai/api-reference/segments/update-a-segment.md): Update a segment in place; the slug is permanent. Changing the filter doesn't re-evaluate membership until the next evaluation. - [Delete a segment](https://docs.useboom.ai/api-reference/segments/delete-a-segment.md): Remove a segment. It disappears from all lists and its journey triggers are disconnected. Idempotent. - [Preview a segment filter](https://docs.useboom.ai/api-reference/segments/preview-a-segment-filter.md): Count how many people currently match a filter, without saving. Use it to check the audience before saving a segment. - [Evaluate a segment now](https://docs.useboom.ai/api-reference/segments/evaluate-a-segment-now.md): Re-evaluate a segment's membership now instead of waiting for its cadence. Runs synchronously; can take a while for large organizations. - [List numbers](https://docs.useboom.ai/api-reference/whatsapp-templates/list-numbers.md): List the WhatsApp numbers connected to your organization. Use them when creating templates. - [List templates](https://docs.useboom.ai/api-reference/whatsapp-templates/list-templates.md): List your WhatsApp templates and each one's approval status. Reviews are async (~24–48h) — re-read to see updates. - [Create template](https://docs.useboom.ai/api-reference/whatsapp-templates/create-template.md): Create a WhatsApp template and submit it for WhatsApp approval, which is asynchronous (~24–48h). Example (TEXT): `{ "name": "order_shipped", "language": "es", "category": "UTILITY", "contentType": "TEXT", "content": { "body": "Hola {{1}}, tu pedido ya salió." }, "variables": { "1": "Ana" } }`. Examp… - [Get template](https://docs.useboom.ai/api-reference/whatsapp-templates/get-template.md): Get one WhatsApp template by id, including its approval status and any rejection reason. - [List email templates](https://docs.useboom.ai/api-reference/email-templates/list-email-templates.md): List the organization's email templates — drafts and published — with their status, authoring mode and variables. A journey's SEND_EMAIL node can only use a PUBLISHED one (journeys_email_templates lists just those, plus sender readiness). - [Get email template](https://docs.useboom.ai/api-reference/email-templates/get-email-template.md): Get one email template in full: its block document (BLOCKS) or HTML source (CODE), the rendered HTML and text, variables and sender picks. Edit what you read and send it back with email_templates_update. - [Create email template](https://docs.useboom.ai/api-reference/email-templates/create-email-template.md): Create an email template as a DRAFT, from either a block `document` (like the drag-and-drop builder) or raw `html`. The deliverable HTML and plain text are produced server-side; {{path}} variables in the subject and body resolve at send. Publish it with email_templates_update (status PUBLISHED) befo… - [Update email template](https://docs.useboom.ai/api-reference/email-templates/update-email-template.md): Update an email template: rename, change the subject or senders, replace its content, or publish/unpublish it (status). Content is re-rendered server-side. Sending `html` to a block template converts it to an HTML template, one way — an HTML template cannot take a `document` again. A PUBLISHED templ… - [List message delivery logs](https://docs.useboom.ai/api-reference/message-logs/list-message-delivery-logs.md): List the messages your organization sent or received and what happened to each one — delivered, failed, or blocked — with the recipient and the failure reason. The same rows as Settings → Logs, so you can review delivery in bulk instead of opening conversations one at a time. ## OpenAPI Specs - [openapi.base](/api-reference/openapi.base.json) - [openapi](/api-reference/openapi.json) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.