Workflows

Workflows are event-triggered automations. When a specified event is tracked for a contact, the workflow starts an execution for that contact and processes each step in sequence.

All workflow endpoints require a secret key (sk_*).

Workflow structure

A workflow consists of:

Trigger — the event name that starts the workflow (e.g. signed_up)
Steps — an ordered set of actions to perform (send email, wait, conditional branch, etc.)
Transitions — connections between steps that optionally include conditions

Step types

Type	Description
`TRIGGER`	Entry point created automatically. Not added manually.
`SEND_EMAIL`	Sends an email using a saved template.
`DELAY`	Pauses the execution for a fixed duration before proceeding.
`WAIT_FOR_EVENT`	Pauses until a specific event is tracked for the contact, or a timeout elapses.
`CONDITION`	Branches the execution based on a boolean expression evaluated against contact data or event data.
`WEBHOOK`	Sends an HTTP request to an external URL with contact and event data.
`UPDATE_CONTACT`	Updates the contact’s data fields with specified key-value pairs.
`EXIT`	Terminates the workflow execution early for the contact.

Execution statuses

Status	Description
`RUNNING`	The execution is actively processing steps.
`WAITING`	The execution is paused on a `DELAY` or `WAIT_FOR_EVENT` step.
`COMPLETED`	The execution finished normally.
`CANCELLED`	The execution was manually cancelled.
`FAILED`	The execution encountered an error.

List workflows

GET /workflows Returns a paginated list of workflows for the authenticated project.

Query parameters

page

number

default:"1"

Page number (1-indexed).

pageSize

number

default:"20"

Items per page. Maximum 100.

string

Filter workflows by name.

Example

curl --request GET \
  --url https://next-api.useplunk.com/workflows \
  --header 'Authorization: Bearer sk_live_yourkey'

Create workflow

POST /workflows Creates a new workflow. The workflow is created in a disabled state — set enabled: true to activate it immediately.

Body parameters

name

string

required

Internal workflow name.

eventName

string

required

The event name that triggers this workflow (e.g. signed_up, purchased). When this event is tracked for a contact, a new execution starts.

enabled

boolean

default:"false"

Whether the workflow is active and will start new executions. Set to true to enable on creation.

allowReentry

boolean

default:"false"

When true, a contact can enter the workflow again even if they have a previous completed or active execution. When false, a contact only runs through the workflow once.

description

string

Optional description.

Example

curl --request POST \
  --url https://next-api.useplunk.com/workflows \
  --header 'Authorization: Bearer sk_live_yourkey' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Welcome Sequence",
    "eventName": "signed_up",
    "enabled": true,
    "allowReentry": false
  }'

Get workflow

GET /workflows/:id Retrieves a single workflow with all of its steps and transitions.

Path parameters

string

required

The workflow ID.

Example

curl --request GET \
  --url https://next-api.useplunk.com/workflows/clx_wf_abc123 \
  --header 'Authorization: Bearer sk_live_yourkey'

Update workflow

PATCH /workflows/:id Updates workflow settings. To add or remove steps, use the step-specific endpoints below.

Path parameters

string

required

The workflow ID.

Body parameters

name

string

Workflow name.

description

string

Workflow description.

enabled

boolean

Enable or disable the workflow. Disabling stops new executions but does not cancel in-progress ones.

allowReentry

boolean

Allow contacts to re-enter the workflow.

triggerType

string

Trigger type (advanced — typically EVENT).

triggerConfig

object

Trigger configuration object (advanced).

Example

curl --request PATCH \
  --url https://next-api.useplunk.com/workflows/clx_wf_abc123 \
  --header 'Authorization: Bearer sk_live_yourkey' \
  --header 'Content-Type: application/json' \
  --data '{
    "enabled": false
  }'

Delete workflow

DELETE /workflows/:id Permanently deletes a workflow.

Deleting a workflow cancels all in-progress executions immediately. This action cannot be undone.

Path parameters

string

required

The workflow ID.

Returns 204 No Content on success.

Example

curl --request DELETE \
  --url https://next-api.useplunk.com/workflows/clx_wf_abc123 \
  --header 'Authorization: Bearer sk_live_yourkey'

List executions

GET /workflows/:id/executions Returns a paginated list of executions for a workflow.

Path parameters

string

required

The workflow ID.

Query parameters

page

number

default:"1"

Page number.

pageSize

number

default:"20"

Items per page. Maximum 100.

status

string

Filter by execution status. One of PENDING, RUNNING, COMPLETED, CANCELLED, FAILED.

Response

executions

array

Array of execution objects.

Show Execution properties

string

Execution ID.

workflowId

string

Parent workflow ID.

contactId

string

Contact the execution is running for.

status

string

Execution status (PENDING, RUNNING, COMPLETED, CANCELLED, FAILED).

createdAt

string

ISO 8601 timestamp when the execution started.

updatedAt

string

ISO 8601 timestamp of the last status change.

Example

curl --request GET \
  --url 'https://next-api.useplunk.com/workflows/clx_wf_abc123/executions?status=RUNNING' \
  --header 'Authorization: Bearer sk_live_yourkey'

200

{
  "executions": [
    {
      "id": "clx_exec_xyz789",
      "workflowId": "clx_wf_abc123",
      "contactId": "clx_contact_def456",
      "status": "RUNNING",
      "createdAt": "2024-01-15T09:00:00.000Z",
      "updatedAt": "2024-01-15T09:05:00.000Z"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 1
}

Cancel execution

DELETE /workflows/:id/executions/:executionId Cancels a specific in-progress execution.

Path parameters

string

required

The workflow ID.

executionId

string

required

The execution ID to cancel.

Example

curl --request DELETE \
  --url https://next-api.useplunk.com/workflows/clx_wf_abc123/executions/clx_exec_xyz789 \
  --header 'Authorization: Bearer sk_live_yourkey'

Cancel all executions

POST /workflows/:id/executions/cancel-all Cancels all active executions (RUNNING or WAITING) for a workflow. Use this before editing a live workflow.

Path parameters

string

required

The workflow ID.

Example

curl --request POST \
  --url https://next-api.useplunk.com/workflows/clx_wf_abc123/executions/cancel-all \
  --header 'Authorization: Bearer sk_live_yourkey'

Add step

POST /workflows/:id/steps Adds a new step to a workflow. Steps are connected via transitions.

Path parameters

string

required

The workflow ID.

Body parameters

type

string

required

Step type. One of SEND_EMAIL, DELAY, WAIT_FOR_EVENT, CONDITION, WEBHOOK, UPDATE_CONTACT, EXIT.

name

string

required

Display name for the step.

position

object

required

Visual position in the workflow editor: { "x": 100, "y": 200 }.

config

object

required

Step configuration. Shape varies by type:

SEND_EMAIL: { "templateId": "uuid" }
DELAY: { "amount": 24, "unit": "hours" }
WAIT_FOR_EVENT: { "eventName": "email.clicked", "timeout": 86400 }
CONDITION: { "field": "contact.data.plan", "operator": "equals", "value": "pro" }
WEBHOOK: { "url": "https://...", "method": "POST", "headers": {} }
UPDATE_CONTACT: { "data": { "key": "value" } }
EXIT: { "reason": "optional reason" }

templateId

string

Template ID shorthand for SEND_EMAIL steps. Equivalent to setting it in config.

autoConnect

boolean

When true, automatically creates a transition from the last step to this new step.

Example

curl --request POST \
  --url https://next-api.useplunk.com/workflows/clx_wf_abc123/steps \
  --header 'Authorization: Bearer sk_live_yourkey' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "SEND_EMAIL",
    "name": "Welcome email",
    "position": { "x": 100, "y": 300 },
    "config": { "templateId": "clx_tmpl_abc123" },
    "autoConnect": true
  }'

Update step

PATCH /workflows/:id/steps/:stepId Updates a workflow step’s name, position, or configuration.

Path parameters

string

required

The workflow ID.

stepId

string

required

The step ID to update.

Body parameters

name

string

New display name.

position

object

New visual position: { "x": number, "y": number }.

config

object

Updated step configuration.

templateId

string

Updated template ID (for SEND_EMAIL steps).

Delete step

DELETE /workflows/:id/steps/:stepId Removes a step from the workflow. Any transitions connected to this step are also removed.

Path parameters

string

required

The workflow ID.

stepId

string

required

The step ID to delete.

Returns 204 No Content on success.

Create transition

POST /workflows/:id/transitions Creates a directed connection between two steps.

Path parameters

string

required

The workflow ID.

Body parameters

fromStepId

string

required

ID of the source step.

toStepId

string

required

ID of the destination step.

condition

object

Optional condition that must be true for this transition to be followed. Used with CONDITION steps to define branches.

priority

number

Order priority when multiple transitions exist from the same step. Lower values are evaluated first.

Delete transition

DELETE /workflows/:id/transitions/:transitionId Removes a transition between two steps.

Path parameters

string

required

The workflow ID.

transitionId

string

required

The transition ID to delete.

Returns 204 No Content on success.

Overview

Endpoints

Workflow structure

Step types

Execution statuses

List workflows

Query parameters

Create workflow

Body parameters

Get workflow

Path parameters

Update workflow

Path parameters

Body parameters

Delete workflow

Path parameters

List executions

Path parameters

Query parameters

Response

Cancel execution

Path parameters

Cancel all executions

Path parameters

Add step

Path parameters

Body parameters

Update step

Path parameters

Body parameters

Delete step

Path parameters

Create transition

Path parameters

Body parameters

Delete transition

Path parameters

Build docs developers (and LLMs) love

Overview

Endpoints

​Workflow structure

​Step types

​Execution statuses

​List workflows

​Query parameters

​Create workflow

​Body parameters

​Get workflow

​Path parameters

​Update workflow

​Path parameters

​Body parameters

​Delete workflow

​Path parameters

​List executions

​Path parameters

​Query parameters

​Response

​Cancel execution

​Path parameters

​Cancel all executions

​Path parameters

​Add step

​Path parameters

​Body parameters

​Update step

​Path parameters

​Body parameters

​Delete step

​Path parameters

​Create transition

​Path parameters

​Body parameters

​Delete transition

​Path parameters

Build docs developers (and LLMs) love

Workflow structure

Step types

Execution statuses

List workflows

Query parameters

Create workflow

Body parameters

Get workflow

Path parameters

Update workflow

Path parameters

Body parameters

Delete workflow

Path parameters

List executions

Path parameters

Query parameters

Response

Cancel execution

Path parameters

Cancel all executions

Path parameters

Add step

Path parameters

Body parameters

Update step

Path parameters

Body parameters

Delete step

Path parameters

Create transition

Path parameters

Body parameters

Delete transition

Path parameters