---
title: "Configure Transactional"
method: PATCH
path: "/api/v1/initiatives/{id}/transactional"
tags: ["Initiatives"]
---

# Configure Transactional

`PATCH /api/v1/initiatives/{id}/transactional`

## Request

- Base URL: `https://www.useboom.ai`
- URL: `https://www.useboom.ai/api/v1/initiatives/{id}/transactional`
- Auth: HTTP bearer

Set up or change a Transactional in one call: the event, optionally the field that identifies each send, its messages with variable bindings, and whether sends wait in Drafts for approval. Only the fields you pass change (null clears one). The journey is rebuilt for you, and a live Transactional goes live with the change immediately. Returns the setup plus `missing`: what still blocks `initiatives_launch`, each with how to fix it. Calling it with only `id` resets a journey edited outside the standard shape.

## Path parameters

- `id` string, required: The Transactional id.

## Request body

- object
  - `eventName` string, nullable: The CDP event that sends the messages, e.g. "payment_link_created". Letters, numbers and underscores only. null clears it.
  - `parallelRunsBy` string, nullable: Optional. Unset (the default) sends one notification per event, one at a time per customer. Set it to an event property, usually an id such as "orderId", for one notification per value: each value sends once per customer, ever, and an event without it sends nothing. null clears it.
  - `whatsapp` object, nullable: The WhatsApp message: an APPROVED template, the sending number (`journeys_message_channels`), and a binding for EVERY placeholder. null removes it.
    - `templateId` string, required
    - `channelId` string, required
    - `templateBindings` object: Template variable → where its value comes from: `engagement.workflowState.<property>` for a property of the triggering event, `person.<field>` for a customer field, or `literal:<text>` for fixed text. WhatsApp keys are the placeholder numbers ("1", "2").
  - `email` object, nullable: The email message: a PUBLISHED template (`journeys_email_templates`). Unbound variables use the template's own value. null removes it.
    - `templateId` string, required
    - `bindings` object: Template variable → where its value comes from: `engagement.workflowState.<property>` for a property of the triggering event, `person.<field>` for a customer field, or `literal:<text>` for fixed text. WhatsApp keys are the placeholder numbers ("1", "2").
  - `reviewBeforeSending` boolean: Every send waits in Drafts until an org member approves or rejects it (`drafts_list`, `drafts_decide`); a rejected email still lets the WhatsApp message go. Without `parallelRunsBy`, a customer's next event is dropped while their earlier send waits, so set a key when events can repeat. Refused (`drafts_disabled`) while drafts are turned off for the organization.
  - `lookup` object, nullable: Loads one custom object record so later steps can use its attributes.
    - `objectType` string: The custom object type name (cdp_custom_object_types_list `name`). Required before publishing.
    - `saveAs` string: The variable name later steps read the record under: saveAs 'brand' → {{brand.logo_url}}, {{brand.primary_color}}; saveAs 'order' → {{order.total | currency:MXN}}. One lowercase word, unique per journey, not customer/person/engagement/event/env. Required before publishing. Publishing checks every <saveAs>.<field> a later step (or its email template) reads is loaded by this node.
    - `lookup` union: How to find the record: 'key' (an id the run carries) or 'relationship' (follow links from the run's person).
      - object
        - `by` 'key', required
        - `keyPath` string, required: A variable path whose value is the record's externalId, e.g. event.merchant_id, engagement.workflowState.merchant_id, person.merchant_id, or a field of another saved record such as order.merchant_id.
      - object
        - `by` 'relationship', required
        - `path` union[], required: Hops from the run's person to the record: first a PERSON_OBJECT edge (relationship role + the linked type's id), then OBJECT_OBJECT edges. [] means the type is linked to the person directly. Must match a path the relationship registries allow (checked at publish); the journey builder lists them.
          - union
            - object
              - …
            - object
              - …
    - `attributes` string[]: The record's attributes to make available to later steps (at least 1, at most 30), read as {{<saveAs>.<attr>}}. Strings longer than 2000 characters are cut.
    - `orderBy` object: When several records match, the one with the lowest ('asc') or highest ('desc') value of this attribute wins; records missing it come last. Without orderBy, several matches load nothing.
      - `attribute` string, required
      - `direction` 'asc' | 'desc', required

## Response `200`

Success

- object
  - `id` string, required
  - `eventName` string, nullable, required
  - `parallelRunsBy` string, nullable, required
  - `whatsapp` object, nullable, required
    - `templateId` string, required
    - `channelId` string, nullable, required
    - `templateBindings` object, required
  - `email` object, nullable, required
    - `templateId` string, required
    - `bindings` object, required
  - `reviewBeforeSending` boolean, required
  - `lookup` object, nullable, required: Loads one custom object record so later steps can use its attributes.
    - `objectType` string: The custom object type name (cdp_custom_object_types_list `name`). Required before publishing.
    - `saveAs` string: The variable name later steps read the record under: saveAs 'brand' → {{brand.logo_url}}, {{brand.primary_color}}; saveAs 'order' → {{order.total | currency:MXN}}. One lowercase word, unique per journey, not customer/person/engagement/event/env. Required before publishing. Publishing checks every <saveAs>.<field> a later step (or its email template) reads is loaded by this node.
    - `lookup` union: How to find the record: 'key' (an id the run carries) or 'relationship' (follow links from the run's person).
      - object
        - `by` 'key', required
        - `keyPath` string, required: A variable path whose value is the record's externalId, e.g. event.merchant_id, engagement.workflowState.merchant_id, person.merchant_id, or a field of another saved record such as order.merchant_id.
      - object
        - `by` 'relationship', required
        - `path` union[], required: Hops from the run's person to the record: first a PERSON_OBJECT edge (relationship role + the linked type's id), then OBJECT_OBJECT edges. [] means the type is linked to the person directly. Must match a path the relationship registries allow (checked at publish); the journey builder lists them.
          - union
            - object
              - …
            - object
              - …
    - `attributes` string[]: The record's attributes to make available to later steps (at least 1, at most 30), read as {{<saveAs>.<attr>}}. Strings longer than 2000 characters are cut.
    - `orderBy` object: When several records match, the one with the lowest ('asc') or highest ('desc') value of this attribute wins; records missing it come last. Without orderBy, several matches load nothing.
      - `attribute` string, required
      - `direction` 'asc' | 'desc', required
  - `journeyStatus` 'DRAFT' | 'PUBLISHED' | 'STOPPED', nullable, required
  - `readyToLaunch` boolean, required: True when nothing below blocks `initiatives_launch`.
  - `missing` object[], required: What still blocks launch, each with how to fix it.
    - `code` string, required
    - `message` string, required

## Other responses

- `400`: Validation failed or the request cannot proceed.
- `401`: Missing, malformed, or revoked API key.
- `404`: The resource does not exist in this organization.
- `409`: Conflicts with the current state (duplicates, wrong lifecycle state).
- `422`: The request is well-formed but semantically invalid.
- `429`: Rate limit exceeded — retry after `Retry-After`.
- `500`: Internal server error.
- `503`: Transient error — retry with a narrower request.

## Changes

- **2026-11-05** `d596d92ed092`: 2 info
  - added the new optional request property `lookup`
  - added the required property `lookup` to the response with the `200` status
- **2026-11-03** `7c7a773b12ce`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/useboom/apis/boom-api/changes/api/v1/initiatives/:id/transactional/patch.md)

---

[API](https://skmtc.dev/useboom/apis/boom-api.md) - [All operations](https://skmtc.dev/useboom/apis/boom-api/llms.txt) - [OpenAPI document](https://skmtc.dev/useboom/apis/boom-api/revisions/d596d92ed092?raw)