Update Structure

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

Parameter	Type	Required	Description
`id`	string (uuid)	Yes	Agent ID

Request Body

Provide statuses, fields, or both.

Field	Type	Required	Description
`statuses`	array	No	Funnel statuses to upsert (see shape below)
`fields`	array	No	Custom lead fields to upsert (see shape below)

`statuses[]` shape

Field	Type	Required	Description
`key`	string	Yes	Stable identifier. Matches an existing status to update it, otherwise inserts a new one
`label`	string	Yes	Display label (`name` also accepted)
`is_initial`	boolean	No	Marks the funnel’s entry status
`is_terminal`	boolean	No	Marks a funnel-ending status
`sort_order`	integer	No	On insert, defaults to array index appended after the current max. Ignored on update — reordering existing statuses isn’t done here

`fields[]` shape

Field	Type	Required	Description
`key`	string	Yes	Stable identifier
`label`	string	Yes	Display label
`type`	string	No	One of: `text`, `number`, `date`, `datetime`, `boolean`, `select`, `multiselect`, `email`, `phone`, `url`, `currency`. Default `text`
`required`	boolean	No	Whether the agent must collect this field before advancing. Default `false`
`sort_order`	integer	No	Same 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

Quick Start

WhatsApp

Agents

Assistant

Advanced

API Reference

Leads

Agents

Workflow Tools

Client Tools

Groups

Campaigns

Conversions

Reports

Conversations

Tags

Messages

Background Jobs

Meetings

Team

Processors

Update Structure

Path Parameters

Request Body

`statuses[]` shape

`fields[]` shape

Responses

`200` — Updated

`400` — Validation error

`401` — Authentication error

`404` — Not found

`500` — Internal server error

​Path Parameters

​Request Body

​statuses[] shape

​fields[] shape

​Responses

​200 — Updated

​400 — Validation error

​401 — Authentication error

​404 — Not found

​500 — Internal server error

Path Parameters

Request Body

`statuses[]` shape

`fields[]` shape

Responses

`200` — Updated

`400` — Validation error

`401` — Authentication error

`404` — Not found

`500` — Internal server error