Get a workflow based on the ID
/v1/workflows/{id}org.permission.workflow.readorg.admin.workflow.readThe API key or user must hold at least one of them. Legacy roles still work; prefer the others for new keys.
Retrieves a workflow based on the Workflow ID.
Workflows
A workflow is an automation that runs inside Kustomer whenever an event happens. A trigger starts each run, and steps call actions, with conditions choosing the path from one step to the next.
Admins build workflows without code in Settings › Platform › Workflows, and apps can install their own. Use them to tag and route conversations, keep records in sync, call your own services when something changes, or handle data from inbound webhooks. Underneath the builder, each workflow is a JSON document, and this API reads and writes that document, so you can back workflows up, review changes in code, or copy them between a sandbox and production.
A workflow is created disabled unless you send enabled: true. Once it's enabled, every matching event starts a run; creating, enabling or changing a workflow takes about a minute to take effect. Runs execute in parallel, finish in any order, and stop after five minutes. There is no delete operation in this API: set enabled to false to stop a workflow.
The document
| Part | What it holds |
|---|---|
trigger |
What starts a run: an eventName such as kustomer.conversation.update, or callable: true with an input schema for workflows that are called rather than triggered by an event. Its output is step 1. |
steps |
The actions to run, each with an id, an action and params. A step's output is stored under its ID for later steps to reference as /#steps.<id>. |
transitions |
On the trigger and each step: where to go next, each guarded by a condition. The first match wins; if none match, the run ends normally. |
errorCases |
On a step: whether to continue or stop when it fails. |
name is required and unique in the org: letters, numbers, -, _ and ., up to 128 characters. replaces names another workflow, usually one an app installed, that this one overrides; when both match an event, only this one runs. See Workflow JSON for every field and limit.
Read-only attributes
Responses also include lastError (the most recent failure, or {}), editable (whether the builder can edit it), containsVariables, and timestamps. Strip these before sending a document back, because unknown keys are rejected with 400.
Which endpoint to use
| To | Call |
|---|---|
List workflows, filtered by enabled, trigger eventName or callable |
GET /v1/workflows |
| Read one workflow | GET /v1/workflows/{id} |
| Create a workflow | POST /v1/workflows |
| Change, enable or disable a workflow | PUT /v1/workflows/{id} |
| Store secrets the workflow uses | POST /v1/workflows/{id}/variables |
| See why runs failed | GET /v1/workflows/{id}/processes |
PUT updates only the root keys you send, and each one replaces the stored value wholesale, so send trigger and steps together and keep step IDs stable because references depend on them. To switch a workflow on or off, send only enabled. Create new workflows disabled, add their variables, then enable them. Workflows reference org-specific IDs such as tags, teams, users and queues, so replace those before copying a workflow to another org. A workflow that updates the record that triggered it fires again, so guard update triggers with a condition on changes.
Path parameters
Unique Workflow ID
"57504f6460da071c000dfaee"Responses
OK