States settings

Kanban board column configuration

INFO

Every response arrives in the shared envelope — code, message, messages, status_code, time — with the payload in data. The tables below describe what is inside data.

POST /states-settings/create

Create a custom workflow state column for an organization and domain type.

Request body

Field	Type	Required	Description
organization_id	string	Yes	Organization ObjectId this state column belongs to
name	string	Yes	Display name of the state column
type	string	Yes	The domain this state column belongs to (STATE_TYPE). One of: trades, saleOrders, deliveryOrders, purchases, purchaseOrders, purchaseRequests
order	number	Yes	Display order within the same type; siblings are re-sequenced automatically
note	string	No	Optional descriptive note for the state column
bg_color	string	No	Background color hex code, e.g. #F1F2F4

{
  "organization_id": "string",
  "name": "string",
  "type": "trades",
  "order": 0,
  "note": "string",
  "bg_color": "string"
}

Response

Field	Type	Description
_id	string
name	string
type	string
is_default	boolean
default_key	string
organization_id	string

{
  "code": 0,
  "message": "Success",
  "status_code": 200,
  "data": {
    "_id": "string",
    "name": "string",
    "type": "string",
    "is_default": false,
    "default_key": "string",
    "organization_id": "string"
  },
  "time": "2025-05-01T12:00:00Z"
}

GET /states-settings/get-by-id/{id}

Fetch a single workflow state column by ObjectId.

Path parameters

Parameter	Type	Required	Description
id	string	Yes	State column ObjectId

Request body

No request body.

Response

Same response shape as POST /states-settings/create.

POST /states-settings/get-paging

Flat sorted list of workflow state columns. Filterable by type, organization, and is_default. Returns a plain array sorted by {type, order} — not a {list, total} envelope.

Request body

Field	Type	Required	Description
type	string	No	Filter by STATE_TYPE domain. One of: trades, saleOrders, deliveryOrders, purchases, purchaseOrders, purchaseRequests
types	string[]	No	Filter by multiple STATE_TYPE values
organization_id	string	No	Filter by organization ObjectId
is_default	boolean	No	When true, return only default (system-seeded) columns; false returns custom ones only

{
  "type": "trades",
  "types": [
    "trades"
  ],
  "organization_id": "string",
  "is_default": false
}

Response

{
  "code": 0,
  "message": "Success",
  "status_code": 200,
  "data": [
    {
      "_id": "string",
      "name": "string",
      "type": "string",
      "is_default": false,
      "default_key": "string",
      "organization_id": "string"
    }
  ],
  "time": "2025-05-01T12:00:00Z"
}

PUT /states-settings/update/{id}

Update an existing workflow state column. Changing order re-sequences sibling columns of the same type. order is silently dropped for default (system-seeded) columns.

Path parameters

Parameter	Type	Required	Description
id	string	Yes	State column ObjectId

Request body

Field	Type	Required	Description
name	string	No	New display name
order	number	No	New display order. Silently dropped for default columns.
note	string	No	Updated note
bg_color	string	No	Updated background color hex code

{
  "name": "string",
  "order": 0,
  "note": "string",
  "bg_color": "string"
}

Response

Same response shape as POST /states-settings/create.

DELETE /states-settings/delete/{id}

Soft-delete a workflow state column (sets is_deleted=true). Guarded: default columns cannot be deleted, and columns still referenced by trade/sale-order/delivery-order documents are rejected with an error.

Path parameters

Parameter	Type	Required	Description
id	string	Yes	State column ObjectId

Request body

No request body.

Response

{
  "code": 0,
  "message": "Success",
  "status_code": 200,
  "data": "string",
  "time": "2025-05-01T12:00:00Z"
}

---

This page is generated from the OpenAPI spec.