Conversion events

Every call needs Authorization: Bearer <key>. 11 calls:

• List conversion deliveries: GET /v1/conversion-deliveries
• List conversion destinations: GET /v1/conversion-destinations
• Create a conversion destination: POST /v1/conversion-destinations
• Update a conversion destination: PATCH /v1/conversion-destinations/:id
• Delete a conversion destination: DELETE /v1/conversion-destinations/:id
• List conversion events: GET /v1/conversion-events
• Create a custom conversion event: POST /v1/conversion-events
• Fire a conversion event: POST /v1/conversion-events/fire
• Update a conversion event: PATCH /v1/conversion-events/:key
• List fired conversion events: GET /v1/conversions
• Get a fired conversion event: GET /v1/conversions/:id

List conversion deliveries

GET /v1/conversion-deliveries

The delivery log, newest first: one row per fired event and destination, with its status, response code, attempts and next attempt. A postback shows its webhook delivery’s.

Query parameters

Name	Type	Required	Description
limit	integer	No	From 1 to 100. Default 50.
cursor	string	No	Opaque cursor from next_cursor. Up to 512 characters.
status	enum	No	One of: pending, delivered, failed, skipped.
destination_id	string	No	Conversion destination id (cdst_...).
connection_id	string	No	Integration connection id (int_...).
conversion_id	string	No	Conversion event id (cev_...).
event_key	string	No	A built-in key (lead.replied) or a custom one (asked_for_pricing). Up to 64 characters.

Headers

Name	Type	Required	Description
x-workspace-id	string	No	Workspace for session (JWT) callers. API keys carry their own workspace.

Response 200

Field	Type	Description
data	object[]
data[].attempts	integer	From 0 to 9007199254740991.
data[].connection_id	string or null	Integration connection id (int_...).
data[].conversion_id	string	Conversion event id (cev_...).
data[].created_at	string (date-time)	ISO 8601 timestamp.
data[].destination_id	string	Conversion destination id (cdst_...).
data[].event_key	string	A built-in key (lead.replied) or a custom one (asked_for_pricing). Up to 64 characters.
data[].id	string (uuid)
data[].kind	enum	One of: crm, ad_platform, postback.
data[].last_error	string or null
data[].next_attempt_at	string (date-time) or null	ISO 8601 timestamp.
data[].response_code	integer or null	From -9007199254740991 to 9007199254740991.
data[].skip_reason	string or null	Why it was skipped, like opted_out or no_consent.
data[].status	enum	One of: pending, delivered, failed, skipped.
data[].updated_at	string (date-time)	ISO 8601 timestamp.
data[].webhook_endpoint_id	string or null	Webhook endpoint id (whk_...).
next_cursor	string or null	Pass as cursor to get the next page; null at the end.

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.

List conversion destinations

GET /v1/conversion-destinations

Query parameters

Name	Type	Required	Description
event_key	string	No	A built-in key (lead.replied) or a custom one (asked_for_pricing). Up to 64 characters.
kind	enum	No	One of: crm, ad_platform, postback.
connection_id	string	No	Integration connection id (int_...).

Headers

Name	Type	Required	Description
x-workspace-id	string	No	Workspace for session (JWT) callers. API keys carry their own workspace.

Response 200

Field	Type	Description
data	object[]
data[].connection_id	string or null	Integration connection id (int_...).
data[].created_at	string (date-time)	ISO 8601 timestamp.
data[].enabled	boolean
data[].event_key	string	A built-in key (lead.replied) or a custom one (asked_for_pricing). Up to 64 characters.
data[].id	string	Conversion destination id (cdst_...).
data[].kind	enum	One of: crm, ad_platform, postback.
data[].mapping	object
data[].provider	string or null	The connection’s provider, for crm and ad_platform.
data[].updated_at	string (date-time)	ISO 8601 timestamp.
data[].webhook_endpoint_id	string or null	Webhook endpoint id (whk_...).

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.

Create a conversion destination

POST /v1/conversion-destinations

Sends an event to a CRM connection (with one action the CRM can take), an ad platform connection (with its event name) or a webhook endpoint (a signed postback). Only events fired after this get a delivery; a built-in event’s system rule looks back 24 hours when its first destination is added.

Headers

Name	Type	Required	Description
x-workspace-id	string	No	Workspace for session (JWT) callers. API keys carry their own workspace.
idempotency-key	string	No	Makes the write safe to retry for 24 hours. 1 to 255 printable characters. Keys starting with outreach:, workflow: or agent: are reserved for messages bubbl3 sends itself and are refused with 400. Up to 255 characters.

Request body

Field	Type	Required	Description
connection_id	string	Yes	Integration connection id (int_...).
enabled	boolean	No	Default true.
event_key	string	Yes	A built-in key (lead.replied) or a custom one (asked_for_pricing). Up to 64 characters.
kind	enum	Yes	One of: crm.
mapping	object	Yes
mapping.action	enum	Yes	One of: set_field.
mapping.field	string	Yes	The CRM's field name, as its API names it. Up to 200 characters.
mapping.value	string	Yes	May use {event_name}, {event_key}, {value}, {currency}, {occurred_at} and {first_name}-style variables. Up to 500 characters.

Response 201

Field	Type	Description
connection_id	string or null	Integration connection id (int_...).
created_at	string (date-time)	ISO 8601 timestamp.
enabled	boolean
event_key	string	A built-in key (lead.replied) or a custom one (asked_for_pricing). Up to 64 characters.
id	string	Conversion destination id (cdst_...).
kind	enum	One of: crm, ad_platform, postback.
mapping	object
provider	string or null	The connection’s provider, for crm and ad_platform.
updated_at	string (date-time)	ISO 8601 timestamp.
webhook_endpoint_id	string or null	Webhook endpoint id (whk_...).

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.

Update a conversion destination

PATCH /v1/conversion-destinations/:id

Turn it on or off, or change its mapping (checked against its kind and provider). Its event, kind and target are fixed.

Path parameters

Name	Type	Required	Description
id	string	Yes	Conversion destination id (cdst_...).

Headers

Name	Type	Required	Description
x-workspace-id	string	No	Workspace for session (JWT) callers. API keys carry their own workspace.
idempotency-key	string	No	Makes the write safe to retry for 24 hours. 1 to 255 printable characters. Keys starting with outreach:, workflow: or agent: are reserved for messages bubbl3 sends itself and are refused with 400. Up to 255 characters.

Request body

Field	Type	Required	Description
enabled	boolean	No
mapping	object	No	Checked against the destination’s kind.

Response 200

Field	Type	Description
connection_id	string or null	Integration connection id (int_...).
created_at	string (date-time)	ISO 8601 timestamp.
enabled	boolean
event_key	string	A built-in key (lead.replied) or a custom one (asked_for_pricing). Up to 64 characters.
id	string	Conversion destination id (cdst_...).
kind	enum	One of: crm, ad_platform, postback.
mapping	object
provider	string or null	The connection’s provider, for crm and ad_platform.
updated_at	string (date-time)	ISO 8601 timestamp.
webhook_endpoint_id	string or null	Webhook endpoint id (whk_...).

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.

Delete a conversion destination

DELETE /v1/conversion-destinations/:id

Its deliveries, sent or not, go with it.

Path parameters

Name	Type	Required	Description
id	string	Yes	Conversion destination id (cdst_...).

Headers

Name	Type	Required	Description
x-workspace-id	string	No	Workspace for session (JWT) callers. API keys carry their own workspace.
idempotency-key	string	No	Makes the write safe to retry for 24 hours. 1 to 255 printable characters. Keys starting with outreach:, workflow: or agent: are reserved for messages bubbl3 sends itself and are refused with 400. Up to 255 characters.

Response 200

Field	Type	Description
deleted	enum	One of: true.
id	string	Conversion destination id (cdst_...).

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.

List conversion events

GET /v1/conversion-events

The catalog: the eight built-in events (always present) and the workspace’s custom events. Built-in events fire on their own (from bubbl3’s system rules) only while an enabled destination or an active webhook endpoint subscribed to conversion.<key> listens for them, and look back 24 hours when one starts listening: while nothing listens, for example when an endpoint is auto-disabled or a Zap is paused, those events aren’t recorded, even in GET /v1/conversions. The “Fire event” workflow step (formerly “Send event”) and POST /v1/conversion-events/fire record any event at any time. In the dashboard the catalog is Settings, Events.

Headers

Name	Type	Required	Description
x-workspace-id	string	No	Workspace for session (JWT) callers. API keys carry their own workspace.

Response 200

Field	Type	Description
data	object[]
data[].builtin	boolean	Built-in events can’t be renamed or deleted.
data[].config	object
data[].config.days	integer	lead.no_response only: days after the first message with no reply. From 1 to 30.
data[].config.label_id	string (uuid) or null	Fire the event when this label is added to a contact (appointment.booked, lead.qualified and custom events).
data[].created_at	string (date-time)	ISO 8601 timestamp.
data[].currency	string or null	ISO 4217 currency code.
data[].default_value_cents	integer or null	Value in the currency’s minor unit (cents). From 0 to 100000000000.
data[].key	string	A built-in key (lead.replied) or a custom one (asked_for_pricing). Up to 64 characters.
data[].name	string
data[].updated_at	string (date-time)	ISO 8601 timestamp.
data[].webhook_event_type	string	conversion.<event key>, for example conversion.lead.replied. Up to 80 characters.

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.

Create a custom conversion event

POST /v1/conversion-events

Keys are lowercase letters, digits and underscores and never contain a dot, so they can’t clash with a built-in event. Endpoints receive it as conversion.<key>.

Headers

Name	Type	Required	Description
x-workspace-id	string	No	Workspace for session (JWT) callers. API keys carry their own workspace.
idempotency-key	string	No	Makes the write safe to retry for 24 hours. 1 to 255 printable characters. Keys starting with outreach:, workflow: or agent: are reserved for messages bubbl3 sends itself and are refused with 400. Up to 255 characters.

Request body

Field	Type	Required	Description
config	object	No
config.label_id	string (uuid) or null	No	Fire the event when this label is added to a contact (appointment.booked, lead.qualified and custom events).
currency	string or null	No	ISO 4217 currency code.
default_value_cents	integer or null	No	Value in the currency’s minor unit (cents). From 0 to 100000000000.
key	string	Yes	A custom event key, like asked_for_pricing.
name	string	Yes	Up to 80 characters.

Response 201

Field	Type	Description
builtin	boolean	Built-in events can’t be renamed or deleted.
config	object
config.days	integer	lead.no_response only: days after the first message with no reply. From 1 to 30.
config.label_id	string (uuid) or null	Fire the event when this label is added to a contact (appointment.booked, lead.qualified and custom events).
created_at	string (date-time)	ISO 8601 timestamp.
currency	string or null	ISO 4217 currency code.
default_value_cents	integer or null	Value in the currency’s minor unit (cents). From 0 to 100000000000.
key	string	A built-in key (lead.replied) or a custom one (asked_for_pricing). Up to 64 characters.
name	string
updated_at	string (date-time)	ISO 8601 timestamp.
webhook_event_type	string	conversion.<event key>, for example conversion.lead.replied. Up to 80 characters.

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.

Fire a conversion event

POST /v1/conversion-events/fire

Records the event for the contact and queues one delivery per enabled destination. The dedupe key is required: the same key twice is one event, and the second call returns the first with duplicate: true (200). A key already used for another event is a 409. Nothing here sends a message.

Headers

Name	Type	Required	Description
x-workspace-id	string	No	Workspace for session (JWT) callers. API keys carry their own workspace.
idempotency-key	string	No	Makes the write safe to retry for 24 hours. 1 to 255 printable characters. Keys starting with outreach:, workflow: or agent: are reserved for messages bubbl3 sends itself and are refused with 400. Up to 255 characters.

Request body

Field	Type	Required	Description
contact_id	string	Yes	Contact id (ctc_...).
currency	string	No	ISO 4217 currency code.
dedupe_key	string	Yes	The same key twice is one event: the second call returns the first. Up to 200 characters.
event_key	string	Yes	A built-in key (lead.replied) or a custom one (asked_for_pricing). Up to 64 characters.
occurred_at	string (date-time)	No	Defaults to now.
value_cents	integer	No	Value in the currency’s minor unit (cents). From 0 to 100000000000.

Response 200

Field	Type	Description
contact_id	string	Contact id (ctc_...).
created_at	string (date-time)	ISO 8601 timestamp.
currency	string or null	ISO 4217 currency code.
dedupe_key	string
duplicate	boolean	True when an event with this dedupe key already existed.
event_key	string	A built-in key (lead.replied) or a custom one (asked_for_pricing). Up to 64 characters.
id	string	Conversion event id (cev_...).
occurred_at	string (date-time)	ISO 8601 timestamp.
source	enum	One of: workflow, system, api.
source_run_id	string (uuid) or null	The workflow run that fired it, for source workflow.
test	enum	Present when a workflow's live test fired it. Test events go to webhook URLs only, never to a CRM or ad platform. One of: true.
value_cents	integer or null	Value in the currency’s minor unit (cents). From 0 to 100000000000.

Response 201

Field	Type	Description
contact_id	string	Contact id (ctc_...).
created_at	string (date-time)	ISO 8601 timestamp.
currency	string or null	ISO 4217 currency code.
dedupe_key	string
duplicate	boolean	True when an event with this dedupe key already existed.
event_key	string	A built-in key (lead.replied) or a custom one (asked_for_pricing). Up to 64 characters.
id	string	Conversion event id (cev_...).
occurred_at	string (date-time)	ISO 8601 timestamp.
source	enum	One of: workflow, system, api.
source_run_id	string (uuid) or null	The workflow run that fired it, for source workflow.
test	enum	Present when a workflow's live test fired it. Test events go to webhook URLs only, never to a CRM or ad platform. One of: true.
value_cents	integer or null	Value in the currency’s minor unit (cents). From 0 to 100000000000.

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.

Update a conversion event

PATCH /v1/conversion-events/:key

Built-in events keep their name; their default value, currency and rule settings can change. config.days is for lead.no_response only.

Path parameters

Name	Type	Required	Description
key	string	Yes	A built-in key (lead.replied) or a custom one (asked_for_pricing). Up to 64 characters.

Headers

Name	Type	Required	Description
x-workspace-id	string	No	Workspace for session (JWT) callers. API keys carry their own workspace.
idempotency-key	string	No	Makes the write safe to retry for 24 hours. 1 to 255 printable characters. Keys starting with outreach:, workflow: or agent: are reserved for messages bubbl3 sends itself and are refused with 400. Up to 255 characters.

Request body

Field	Type	Required	Description
config	object	No
config.days	integer	No	lead.no_response only: days after the first message with no reply. From 1 to 30.
config.label_id	string (uuid) or null	No	Fire the event when this label is added to a contact (appointment.booked, lead.qualified and custom events).
currency	string or null	No	ISO 4217 currency code.
default_value_cents	integer or null	No	Value in the currency’s minor unit (cents). From 0 to 100000000000.
name	string	No	Up to 80 characters.

Response 200

Field	Type	Description
builtin	boolean	Built-in events can’t be renamed or deleted.
config	object
config.days	integer	lead.no_response only: days after the first message with no reply. From 1 to 30.
config.label_id	string (uuid) or null	Fire the event when this label is added to a contact (appointment.booked, lead.qualified and custom events).
created_at	string (date-time)	ISO 8601 timestamp.
currency	string or null	ISO 4217 currency code.
default_value_cents	integer or null	Value in the currency’s minor unit (cents). From 0 to 100000000000.
key	string	A built-in key (lead.replied) or a custom one (asked_for_pricing). Up to 64 characters.
name	string
updated_at	string (date-time)	ISO 8601 timestamp.
webhook_event_type	string	conversion.<event key>, for example conversion.lead.replied. Up to 80 characters.

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.

List fired conversion events

GET /v1/conversions

Newest first. Filter by contact or event.

Query parameters

Name	Type	Required	Description
limit	integer	No	From 1 to 100. Default 50.
cursor	string	No	Opaque cursor from next_cursor. Up to 512 characters.
event_key	string	No	A built-in key (lead.replied) or a custom one (asked_for_pricing). Up to 64 characters.
contact_id	string	No	Contact id (ctc_...).

Headers

Name	Type	Required	Description
x-workspace-id	string	No	Workspace for session (JWT) callers. API keys carry their own workspace.

Response 200

Field	Type	Description
data	object[]
data[].contact_id	string	Contact id (ctc_...).
data[].created_at	string (date-time)	ISO 8601 timestamp.
data[].currency	string or null	ISO 4217 currency code.
data[].dedupe_key	string
data[].event_key	string	A built-in key (lead.replied) or a custom one (asked_for_pricing). Up to 64 characters.
data[].id	string	Conversion event id (cev_...).
data[].occurred_at	string (date-time)	ISO 8601 timestamp.
data[].source	enum	One of: workflow, system, api.
data[].source_run_id	string (uuid) or null	The workflow run that fired it, for source workflow.
data[].test	enum	Present when a workflow's live test fired it. Test events go to webhook URLs only, never to a CRM or ad platform. One of: true.
data[].value_cents	integer or null	Value in the currency’s minor unit (cents). From 0 to 100000000000.
next_cursor	string or null	Pass as cursor to get the next page; null at the end.

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.

Get a fired conversion event

GET /v1/conversions/:id

Path parameters

Name	Type	Required	Description
id	string	Yes	Conversion event id (cev_...).

Headers

Name	Type	Required	Description
x-workspace-id	string	No	Workspace for session (JWT) callers. API keys carry their own workspace.

Response 200

Field	Type	Description
contact_id	string	Contact id (ctc_...).
created_at	string (date-time)	ISO 8601 timestamp.
currency	string or null	ISO 4217 currency code.
dedupe_key	string
event_key	string	A built-in key (lead.replied) or a custom one (asked_for_pricing). Up to 64 characters.
id	string	Conversion event id (cev_...).
occurred_at	string (date-time)	ISO 8601 timestamp.
source	enum	One of: workflow, system, api.
source_run_id	string (uuid) or null	The workflow run that fired it, for source workflow.
test	enum	Present when a workflow's live test fired it. Test events go to webhook URLs only, never to a CRM or ad platform. One of: true.
value_cents	integer or null	Value in the currency’s minor unit (cents). From 0 to 100000000000.

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.