Skip to main content
Version: v3

Update Workflow Definition

PUT 
/workflows/:workflowId/definition

Replace a workflow definition in full. This is a complete overwrite — any step absent from the request is deleted, so always read the current definition first and send it back modified — the definition carries its own version, so sending back what you read keeps you protected against overwriting a concurrent edit. A stale version is rejected with 422 and nothing is written.

Draft only. A published workflow is rejected with 409: the overwrite would replace steps under contacts currently moving through it. Set the workflow to draft with Update Workflow Status, update it, then publish it again.

Order matters. Changing status advances the version, so read the definition after setting the workflow to draft: draft → read → update → publish. Reading first and drafting second leaves you holding a stale version.

Request​

Version stringrequired

API Version

Available optionsv3
workflowId stringrequired

Workflow ID

locationId stringrequired

Sub-account (location) ID the workflow belongs to

application/json

Bodyrequired

    namestringrequired

    Workflow name

    sourceobjectrequired

    Where this definition came from

    triggersobject[]required

    Triggers that enrol contacts. May be empty — a workflow with no trigger can still be entered by another workflow or by the API — but the key must be present.

    triggerRelationstring

    How multiple triggers combine. Echoed by Get Workflow Definition; ignored on write — the system always stores or.

    Available optionsandor
    actionsobject[]required

    Steps. May be an empty array, but the key must be present.

    edgesobject[]required

    Connections between steps. May be empty, but the key must be present.

    settingsobject

    Workflow-level settings

    folderNamestring

    Single-segment folder to place the workflow in. Mutually exclusive with folderPath.

    folderPathstring[]

    Folder path, outermost first, max 10 levels. Mutually exclusive with folderName.

    createFolderIfMissingboolean

    Create the folder if it does not exist. Requires folderName or folderPath.

    versionnumberrequired

    The workflow's version counter, owned by the system — not a format version. Get Workflow Definition fills it in; leave it untouched and send it back on update, and a concurrent edit in the builder can never be silently overwritten. A stale value is rejected with 422.

    Treat it as opaque: echo it, never compute from it. It does not always advance by one (delete and restore each add 0.1, and a later save rounds up), so it is not always an integer.

    Required on update: send back the value you read. An update without it is rejected with 422 before anything is written.

application/json

Workflow updated

Schema
    workflowIdstringrequired

    Workflow ID

    statusstring

    Whether the workflow is live. Read-only here — change it with Update Workflow Status, which is gated by the workflows.publish scope. Absent only in the rare case where the update succeeded but the workflow could not be read back.

    Available optionsdraftpublished
    definitionobject

    The updated workflow, in the same shape Get Workflow Definition returns and this endpoint accepts — so a follow-up edit needs no separate read. Note version has advanced: an update increments the counter, and sending a stale one is rejected with 422. Absent only if the update succeeded but the workflow could not be read back.

    warningsobject[]required

    Non-blocking findings