Status Definitions API

Canonical status catalog and transition rules shared across all domains

Overview

The Status Definitions API provides the canonical list of available statuses for each entity type. Use this endpoint to populate dropdowns, badges, timelines, and status transition UIs without hardcoding values in the frontend.

Supported Entity Types

case, inquiry, order, offer, message, invoice, contract, sign_request, product

Primary Use Cases

Populate status pickers and badges
Drive transition dropdowns in UI forms
Explain allowed next statuses in workflow screens

Method	Endpoint	Description	Requirements
GET	/api/status-definitions	List status definitions for all entity types or a specific entity type	`entity_type (optional) - Filter by entity type (for example: offer, case, inquiry)` `grouped (optional, default true) - true returns grouped by entity_type; false returns a flat array`
GET	/api/status-definitions/transitions	List allowed transitions, optionally filtered by entity type and source status	`entity_type (optional) - Filter by entity type` `from_status (optional) - Filter transitions from one source status` `grouped (optional, default true) - true returns nested groups by entity_type and from_status`

Request Examples

Get Definitions for One Entity Type

GET /api/status-definitions?entity_type=offer&grouped=false

{ "success": true, "count": 6, "grouped": false, "data": [ { "entity_type": "offer", "key": "draft", "label": "Draft", "color": "#6B7280", "sort_order": 1, "is_initial": true, "is_terminal": false } ] }

Get Transition Rules

GET /api/status-definitions/transitions?entity_type=offer&from_status=sent

{ "success": true, "count": 2, "grouped": true, "data": { "offer": { "sent": [ { "from_status": "sent", "to_status": "viewed" }, { "from_status": "sent", "to_status": "accepted" } ] } } }