Skip to main content
PATCH /workflows/:id/structure Add or edit an agent’s funnel statuses and custom lead fields. Rows are upserted by key: an unrecognized key is inserted, an existing key is updated. This endpoint never deletes — removing a status or field stays a deliberate dashboard action, so leads already sitting on a status are never orphaned.

​
Path Parameters

ParameterTypeRequiredDescription
idstring (uuid)YesAgent ID

​
Request Body

Provide statuses, fields, or both.
FieldTypeRequiredDescription
statusesarrayNoFunnel statuses to upsert (see shape below)
fieldsarrayNoCustom lead fields to upsert (see shape below)

​
statuses[] shape

FieldTypeRequiredDescription
keystringYesStable identifier. Matches an existing status to update it, otherwise inserts a new one
labelstringYesDisplay label (name also accepted)
is_initialbooleanNoMarks the funnel’s entry status
is_terminalbooleanNoMarks a funnel-ending status
sort_orderintegerNoOn insert, defaults to array index appended after the current max. Ignored on update — reordering existing statuses isn’t done here

​
fields[] shape

FieldTypeRequiredDescription
keystringYesStable identifier
labelstringYesDisplay label
typestringNoOne of: text, number, date, datetime, boolean, select, multiselect, email, phone, url, currency. Default text
requiredbooleanNoWhether the agent must collect this field before advancing. Default false
sort_orderintegerNoSame insert/update behavior as statuses

​
Responses

​
200 — Updated

{
  "success": true,
  "workflow_id": "123e4567-e89b-12d3-a456-426614174000",
  "statuses_upserted": 2,
  "fields_upserted": 1
}
statuses_upserted / fields_upserted are only present for the arrays you sent.

​
400 — Validation error

{
  "error": "Invalid input",
  "message": "Provide statuses and/or fields arrays"
}
Also returned as "each status needs a key and a label" or "each field needs a key and a label".

​
401 — Authentication error

See Authentication.

​
404 — Not found

{
  "error": "Not found",
  "message": "Workflow not found"
}

​
500 — Internal server error

Last modified on July 10, 2026