Skip to main content
Version: v4

Create Workflow

POST 
/workflows/

Create a workflow from a complete definition. The definition is validated in full before anything is persisted, so a rejected request creates nothing. Workflows are always created in draft; use Update Workflow Status to publish.

Request​

Version stringrequired

API Version

Available optionsv4
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.

    versionnumber

    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.

    Omit it on create — the system assigns the starting value.

application/json

Workflow created

Schema
    workflowIdstringrequired

    ID of the created workflow

    statusstring

    Status of the new workflow. Always draft — creating something already live is not possible. Absent only in the rare case where the workflow was created but could not be read back.

    Available optionsdraftpublished
    definitionobject

    The created workflow, in the same shape Get Workflow Definition returns and Update Workflow Definition accepts — so an update needs no separate read. Note version is not 1: the create path saves several times. Absent only if the workflow was created but could not be read back.

    warningsobject[]required

    Non-blocking findings