{ "openapi": "3.0.0", "info": { "title": "Workflows Definitions", "version": "1.1.0", "description": "The Workflows Definitions API enables you to create, manage, and configure reusable workflow templates\nwithin your organization. Workflow definitions serve as blueprints that define the structure and behavior\nof business processes, which can then be instantiated as workflow executions.\n\n## Core Concepts\n\n### Workflow Definition (V1)\nA workflow definition is a template that describes a business process. It consists of:\n- **Sections**: Logical groupings (phases) that organize related steps together\n- **Steps**: Individual tasks or actions that need to be completed within a section\n- **Closing Reasons**: Predefined reasons that can be selected when closing/completing a workflow\n\n### Flow Template (V2)\nThe modern workflow model that provides advanced capabilities:\n- **Phases**: Named stages that group related tasks and track progress through the workflow\n- **Tasks**: Individual units of work that can be manual, automated, AI-powered, or decision points\n- **Edges**: Connections between tasks that define the flow sequence and support conditional branching\n- **Triggers**: Define how a workflow is started (manual, automation, journey submission)\n\n### Task Types (V2)\n- **MANUAL**: Tasks assigned to users that require human action to complete\n- **AUTOMATION**: Tasks that execute automated actions when reached\n- **DECISION**: Conditional branching points that evaluate conditions to determine the next path\n- **AI_AGENT**: Tasks that invoke AI agents to perform intelligent actions\n\n## API Versions\n- **V1 endpoints** (`/v1/workflows/...`): Legacy linear workflow model with sections and steps\n- **V2 endpoints** (`/v2/flows/...`): Modern graph-based flow model with phases, tasks, and edges\n" }, "tags": [ { "name": "Workflows", "description": "Manage V1 workflow definitions with sections and steps. These endpoints support the legacy\nlinear workflow model where definitions contain a sequential flow of sections and steps.\n" }, { "name": "Flows V2", "description": "Manage V2 flow templates with phases, tasks, and edges. The modern workflow model supports\nadvanced features including conditional branching, multiple trigger types, automation tasks,\nAI agent tasks, and flexible task dependencies.\n" }, { "name": "Closing Reason", "description": "Manage closing reasons that can be associated with workflows. Closing reasons provide\npredefined options for users to select when closing or completing a workflow execution,\nenabling better tracking and reporting of workflow outcomes.\n" } ], "security": [ { "BearerAuth": [] } ], "paths": { "/v1/workflows/limits/max-allowed": { "get": { "operationId": "getMaxAllowedLimit", "summary": "getMaxAllowedLimit", "description": "Get limits and number of created executions for an Organization.", "tags": [ "Workflows" ], "responses": { "200": { "description": "A combo of current number of workflows, and the max allowed number of workflows.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaxAllowedLimit" }, "example": { "currentNoOfWorkflows": 5, "maxAllowed": 7 } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } } } } }, "/v1/workflows/definitions": { "get": { "operationId": "getDefinitions", "summary": "getDefinitions", "description": "Retrieve all V1 workflow definitions belonging to the authenticated organization.", "tags": [ "Workflows" ], "responses": { "200": { "description": "Success - definitions loaded with success. Empty array if org has no definitions.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowDefinition" } }, "example": [ { "id": "25n2k52ja", "name": "Lead Qualification", "assignedTo": [ "18625", "90252" ], "description": "Lead Qualification description", "lastUpdateTime": "2021-08-04T21:13:50.373Z", "creationTime": "2021-08-04T21:13:50.373Z", "dueDate": "2021-08-04T21:13:50.373Z", "flow": [ { "id": "5892na2", "name": "Initial Information Gathering", "order": 1, "type": "SECTION", "steps": [ { "id": "2hja82a", "name": "Call client and confirm address and product", "type": "STEP", "order": 1, "assignedTo": [ "123482" ] }, { "id": "ga92ha2", "name": "Check product availability", "type": "STEP", "order": 2, "assignedTo": [ "123482" ] }, { "id": "jga92ha", "name": "Send email confirming contact with the client", "type": "STEP", "order": 3, "assignedTo": [ "123482" ] } ] }, { "id": "0a7g22a", "name": "Print and send catalog", "type": "STEP", "order": 2, "assignedTo": [ "123482" ] } ] } ] } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } } } }, "post": { "operationId": "createDefinition", "summary": "createDefinition", "description": "Create a new V1 workflow definition. The definition consists of sections and steps\nthat define the structure of the workflow. Once created, the definition can be used\nto start workflow executions.\n", "tags": [ "Workflows" ], "requestBody": { "description": "Workflow Definition payload", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowDefinition" }, "example": { "name": "Lead Qualification", "description": "Lead Qualification description", "dueDate": "2022-08-04T12:00:00.000Z", "assignedTo": [ "952802", "80225" ], "flow": [ { "name": "Initial Information Gathering", "order": 1, "type": "SECTION", "steps": [ { "name": "Call client and confirm address and product", "type": "STEP", "order": 1, "assignedTo": [ "123482" ] }, { "name": "Check product availability", "type": "STEP", "order": 2, "assignedTo": [ "123482" ] }, { "name": "Send email confirming contact with the client", "type": "STEP", "order": 3, "assignedTo": [ "123482" ] } ] }, { "name": "Print and send catalog", "type": "STEP", "order": 2, "assignedTo": [ "123482" ] } ] } } } }, "responses": { "201": { "description": "Success - if the definition is created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowDefinition" }, "example": { "id": "25n2k52ja", "name": "Lead Qualification", "description": "Lead Qualification description", "lastUpdateTime": "2021-08-04T21:13:50.373Z", "creationTime": "2021-08-04T21:13:50.373Z", "dueDate": "2022-08-04T12:00:00.000Z", "assignedTo": [ "952802", "80225" ], "flow": [ { "id": "5892na2", "name": "Initial Information Gathering", "order": 1, "type": "SECTION", "steps": [ { "id": "2hja82a", "name": "Call client and confirm address and product", "type": "STEP", "order": 1, "assignedTo": [ "48829" ] }, { "id": "ga92ha2", "name": "Check product availability", "type": "STEP", "order": 2, "assignedTo": [ "45390" ] }, { "id": "jga92ha", "name": "Send email confirming contact with the client", "type": "STEP", "order": 3, "assignedTo": [ "8230" ] } ] }, { "id": "0a7g22a", "name": "Print and send catalog", "type": "STEP", "order": 2, "assignedTo": [ "8239" ] } ] } } } }, "400": { "description": "Validation Errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } }, "401": { "description": "Authentication Errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } }, "500": { "description": "Other errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } } } } }, "/v2/flows/templates": { "get": { "operationId": "listFlowTemplates", "summary": "listFlowTemplates", "description": "List all Flow Templates for a customer. Optionally, you can filter flow templates by trigger values.", "tags": [ "Flows V2" ], "parameters": [ { "in": "query", "name": "trigger_type", "schema": { "type": "string", "enum": [ "automation", "manual", "journey_submission" ] }, "required": false, "description": "Type of trigger for whom to filter flow templates", "example": "journey_submission" }, { "in": "query", "name": "trigger_source_id", "schema": { "type": "string" }, "required": false, "description": "Id of the trigger source to filter flow templates. Interpretation depends on **trigger_type**:\n- **automation**: use an `{automation_flow_id}` value\n- **journey_submission**: use a `{journey_id}` value\n- **manual**: this parameter is ignored; you can optionally filter by `{trigger_schema}`\n", "example": "j208g0aj-08g9agajggak-g9aug9-892kgl1m" }, { "in": "query", "name": "trigger_schema", "schema": { "type": "string" }, "required": false, "description": "Schema of the trigger source to filter flow templates. This parameter only makes sense when **trigger_type** is `manual`\n", "example": "opportunity" } ], "responses": { "200": { "description": "Success - flow templates loaded with success. Empty array if customer has no flows defined.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowTemplatesList" } } } }, "500": { "description": "Other errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } } } }, "post": { "operationId": "createFlowTemplate", "summary": "createFlowTemplate", "description": "Create a new Flow Template (V2 workflow definition).\n\nA flow template defines the structure of a workflow including its phases, tasks,\nedges (connections between tasks), and trigger configuration. Once created, the\ntemplate can be used to start workflow executions.\n", "tags": [ "Flows V2" ], "parameters": [ { "$ref": "#/components/parameters/EnforceLimitsParam" } ], "requestBody": { "description": "Flow Template payload containing the workflow structure.\n\nRequired fields:\n- `name`: Display name for the workflow\n- `tasks`: Array of task definitions (manual, automation, decision, or AI agent tasks)\n- `edges`: Array of connections defining the flow between tasks\n", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFlowTemplate" }, "example": { "name": "Customer Onboarding", "description": "Standard customer onboarding workflow with verification steps", "version": "v3", "enabled": true, "trigger": { "type": "manual", "entity_schema": "contact" }, "phases": [ { "id": "phase_1", "name": "Verification" }, { "id": "phase_2", "name": "Setup" } ], "tasks": [ { "id": "task_1", "name": "Verify customer identity", "task_type": "MANUAL", "phase_id": "phase_1", "assigned_to": [ "user_123" ] }, { "id": "task_2", "name": "Send welcome email", "task_type": "AUTOMATION", "phase_id": "phase_2", "automation_config": { "flow_id": "automation_456" }, "trigger_mode": "automatic" }, { "id": "task_3", "name": "Schedule follow-up", "task_type": "MANUAL", "phase_id": "phase_2" } ], "edges": [ { "id": "edge_1", "from_id": "task_1", "to_id": "task_2" }, { "id": "edge_2", "from_id": "task_2", "to_id": "task_3" } ], "closing_reasons": [ { "id": "reason_completed" }, { "id": "reason_cancelled" } ] } } } }, "responses": { "201": { "description": "Success - if the flow template is created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowTemplate" } } } }, "400": { "description": "Validation Errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } }, "401": { "description": "Authentication Errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } }, "500": { "description": "Other errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } } } } }, "/v2/flows/templates:search": { "post": { "operationId": "searchFlowTemplates", "summary": "searchFlowTemplates", "description": "Search for flow templates by name, trigger type, enabled status, and more.", "tags": [ "Flows V2" ], "requestBody": { "description": "Search for flow templates by name, trigger type, enabled status, and more.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchFlowTemplates" }, "example": { "name": "Lead Qualification", "definition_id": "25n2k52ja", "trigger_type": "journey_submission", "enabled": true, "from": 0, "size": 10 } } } }, "responses": { "200": { "description": "Success - flow templates loaded with success. Empty array if customer has no flows defined.", "content": { "application/json": { "schema": { "type": "object", "properties": { "hits": { "type": "number" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/FlowTemplate" } } } } } } }, "500": { "description": "Other errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } } } } }, "/v2/flows/templates/{flowId}": { "get": { "operationId": "getFlowTemplate", "summary": "getFlowTemplate", "description": "Retrieve a specific flow template by its unique identifier.", "tags": [ "Flows V2" ], "parameters": [ { "in": "path", "name": "flowId", "schema": { "$ref": "#/components/schemas/FlowTemplateId" }, "required": true, "description": "Unique identifier of the flow template to retrieve." } ], "responses": { "200": { "description": "Returns the Flow Template", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowTemplate" } } } }, "400": { "description": "Validation Errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } }, "401": { "description": "Authentication Errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } }, "404": { "description": "Definition Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DefinitionNotFoundResp" } } } }, "500": { "description": "Other errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } } } }, "put": { "operationId": "updateFlowTemplate", "summary": "updateFlowTemplate", "description": "Update Flow Template.", "tags": [ "Flows V2" ], "parameters": [ { "in": "path", "name": "flowId", "schema": { "$ref": "#/components/schemas/FlowTemplateId" }, "required": true, "description": "Unique identifier of the flow template to update." }, { "$ref": "#/components/parameters/EnforceLimitsParam" } ], "requestBody": { "description": "Updated flow template payload containing the full workflow definition.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowTemplate" } } } }, "responses": { "200": { "description": "Flow template has been updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowTemplate" } } } }, "400": { "description": "Validation errors - request body contains invalid data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } }, "401": { "description": "Authentication failed - invalid or missing Bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } }, "404": { "description": "Flow template not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DefinitionNotFoundResp" } } } }, "409": { "description": "Conflict - the workflow was modified by another user since it was last loaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } } } }, "delete": { "operationId": "deleteFlowTemplate", "summary": "deleteFlowTemplate", "description": "Delete Flow Template.", "tags": [ "Flows V2" ], "parameters": [ { "in": "path", "name": "flowId", "schema": { "$ref": "#/components/schemas/FlowTemplateId" }, "required": true, "description": "Unique identifier of the flow template to be deleted." } ], "responses": { "204": { "description": "Flow template has been deleted successfully" }, "401": { "description": "Failed to authenticate", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } }, "404": { "description": "Flow template not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DefinitionNotFoundResp" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } } } } }, "/v2/flows/templates/{flowId}/duplicate": { "post": { "operationId": "duplicateFlowTemplate", "summary": "duplicateFlowTemplate", "description": "Create a copy of an existing flow template. The duplicated template will have a new\nunique identifier and can be modified independently of the original. This is useful\nfor creating variations of existing workflows without starting from scratch.\n", "tags": [ "Flows V2" ], "parameters": [ { "in": "path", "name": "flowId", "schema": { "$ref": "#/components/schemas/FlowTemplateId" }, "required": true, "description": "Unique identifier of the flow template to duplicate." } ], "responses": { "201": { "description": "Flow template has been duplicated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowTemplate" } } } }, "400": { "description": "Validation errors - source template contains invalid data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } }, "401": { "description": "Authentication failed - invalid or missing Bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } }, "404": { "description": "Source flow template not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DefinitionNotFoundResp" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } } } } }, "/v1/workflows/definitions/{definitionId}": { "get": { "operationId": "getDefinition", "summary": "getDefinition", "description": "Get specific Definition by id from the Organization.", "tags": [ "Workflows" ], "parameters": [ { "in": "path", "name": "definitionId", "schema": { "type": "string" }, "required": true, "description": "Short uuid (length 8) to identify the Workflow Definition.", "example": "7hj28a" } ], "responses": { "200": { "description": "Returns the Workflow definition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowDefinition" }, "example": { "id": "25n2k52ja", "name": "Lead Qualification", "dueDate": "2022-08-04T12:00:00.000Z", "assignedTo": [ "952802", "80225" ], "lastUpdateTime": "2021-08-04T21:13:50.373Z", "creationTime": "2021-08-04T21:13:50.373Z", "flow": [ { "id": "5892na2", "name": "Initial Information Gathering", "order": 1, "type": "SECTION", "steps": [ { "id": "2hja82a", "name": "Call client and confirm address and product", "type": "STEP", "order": 1, "assignedTo": [ "923432" ] }, { "id": "ga92ha2", "name": "Check product availability", "type": "STEP", "order": 2, "assignedTo": [ "45488" ] }, { "id": "jga92ha", "name": "Send email confirming contact with the client", "type": "STEP", "order": 3, "assignedTo": [ "45488" ] } ] }, { "id": "0a7g22a", "name": "Print and send catalog", "type": "STEP", "order": 2, "assignedTo": [ "8988" ] } ], "closingReasons": [ { "id": "ffoowef", "title": "test" }, { "id": "hebwoeu", "title": "Closing because all" }, { "id": "mbnoenq", "title": "Better offer" } ] } } } }, "400": { "description": "Validation Errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } }, "401": { "description": "Authentication Errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } }, "404": { "description": "Definition Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DefinitionNotFoundResp" } } } }, "500": { "description": "Other errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } } } }, "put": { "operationId": "updateDefinition", "summary": "updateDefinition", "description": "Update Workflow Definition.", "tags": [ "Workflows" ], "parameters": [ { "in": "path", "name": "definitionId", "schema": { "type": "string" }, "required": true, "description": "Short uuid (length 8) to identify the Workflow Definition.", "example": "7hj28a" } ], "requestBody": { "description": "Workflow Definition payload", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowDefinition" }, "example": { "id": "25n2k52ja", "name": "Lead Qualification", "dueDate": "2022-08-04T12:00:00.000Z", "assignedTo": [ "952802", "80225" ], "lastUpdateTime": "2021-08-04T21:13:50.373Z", "creationTime": "2021-08-04T21:13:50.373Z", "flow": [ { "id": "5892na2", "name": "Initial Information Gathering", "order": 1, "type": "SECTION", "steps": [ { "id": "2hja82a", "name": "Call client and confirm address and product", "type": "STEP", "order": 1, "assignedTo": [ "8988" ] }, { "id": "ga92ha2", "name": "Check product availability", "type": "STEP", "order": 2, "assignedTo": [ "8988" ] }, { "id": "jga92ha", "name": "Send email confirming contact with the client", "type": "STEP", "order": 3, "assignedTo": [ "8988" ] } ] }, { "id": "0a7g22a", "name": "Print and send catalog", "type": "STEP", "order": 2, "assignedTo": [ "8988" ] } ] } } } }, "responses": { "200": { "description": "Success - if the definition is updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowDefinition" }, "example": { "id": "25n2k52ja", "name": "Lead Qualification", "dueDate": "2022-08-04T12:00:00.000Z", "assignedTo": [ "952802", "80225" ], "lastUpdateTime": "2021-08-04T21:13:50.373Z", "creationTime": "2021-08-04T21:13:50.373Z", "flow": [ { "id": "5892na2", "name": "Initial Information Gathering", "order": 1, "type": "SECTION", "steps": [ { "id": "2hja82a", "name": "Call client and confirm address and product", "type": "STEP", "order": 1, "assignedTo": [ "1" ] }, { "id": "ga92ha2", "name": "Check product availability", "type": "STEP", "order": 2, "assignedTo": [ "56645" ] }, { "id": "jga92ha", "name": "Send email confirming contact with the client", "type": "STEP", "order": 3, "assignedTo": [ "949923" ] } ] }, { "id": "0a7g22a", "name": "Print and send catalog", "type": "STEP", "order": 2, "assignedTo": [ "156645" ] } ] } } } }, "400": { "description": "Validation Errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } }, "401": { "description": "Authentication Errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } }, "500": { "description": "Other errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } } } }, "delete": { "operationId": "deleteDefinition", "summary": "deleteDefinition", "description": "Delete Workflow Definition.", "tags": [ "Workflows" ], "parameters": [ { "in": "path", "name": "definitionId", "schema": { "type": "string" }, "required": true, "description": "Unique identifier of the workflow definition to be deleted.", "example": "CustomerRequest" } ], "responses": { "204": { "description": "Success - if the definition is deleted successfully" }, "401": { "description": "Failed to authenticate", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } }, "404": { "description": "No definition found" } } } }, "/v1/workflows/closing-reasons": { "get": { "operationId": "getAllClosingReasons", "summary": "getAllClosingReasons", "description": "Get all Closing Reasons defined in the organization by default all Active.", "parameters": [ { "in": "query", "name": "includeInactive", "schema": { "type": "boolean" }, "required": false, "description": "When set to true, includes inactive closing reasons in the response. By default, only active closing reasons are returned.", "example": true } ], "tags": [ "Closing Reason" ], "responses": { "200": { "description": "Returns the entire catalog of closing reasons per organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClosingReasons" } } } } } }, "post": { "operationId": "createClosingReason", "summary": "createClosingReason", "description": "A created Closing Reason is stored for the organization and will be displayed in the library of reasons.", "tags": [ "Closing Reason" ], "requestBody": { "description": "closing reason to store", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClosingReason" }, "example": { "title": "better offer", "description": "A customer closes the process because he found something better" } } } }, "responses": { "201": { "description": "closing reason is stored successfully in the repository", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClosingReason" } } } } } } }, "/v2/workflows/closing-reasons/{reasonId}": { "get": { "operationId": "getClosingReason", "summary": "getClosingReason", "description": "Get specific closing reason by id from the organisation.", "tags": [ "Closing Reason" ], "parameters": [ { "in": "path", "name": "reasonId", "schema": { "type": "string", "example": "x739cew" }, "required": true, "description": "unique id to identify the closing reason." } ], "responses": { "200": { "description": "Returns the closing reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClosingReason" } } } }, "400": { "description": "Validation Errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } }, "404": { "description": "Closing reason not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClosingReasonNotFoundResp" } } } } } }, "patch": { "operationId": "updateClosingReason", "summary": "updateClosingReason", "description": "Update an existing closing reason", "tags": [ "Closing Reason" ], "parameters": [ { "in": "path", "name": "reasonId", "schema": { "type": "string", "example": "x739cew" }, "required": true, "description": "unique id to identify the closing reason." } ], "requestBody": { "description": "Updated closing reason fields", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClosingReason" } } } }, "responses": { "200": { "description": "Closing reason updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClosingReason" } } } }, "400": { "description": "Validation Errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } }, "404": { "description": "Closing reason not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClosingReasonNotFoundResp" } } } } } }, "delete": { "operationId": "deleteClosingReason", "summary": "deleteClosingReason", "description": "Permanently delete a closing reason (Using INACTIVE status is recommended instead)", "tags": [ "Closing Reason" ], "parameters": [ { "in": "path", "name": "reasonId", "schema": { "type": "string", "example": "x739cew" }, "required": true, "description": "unique id to identify the closing reason." } ], "responses": { "204": { "description": "Closing reason deleted successfully" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } }, "404": { "description": "Closing reason not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClosingReasonNotFoundResp" } } } } } } }, "/v1/workflows/closing-reasons/{reasonId}": { "get": { "deprecated": true, "operationId": "getClosingReasonV1", "summary": "getClosingReasonV1", "description": "Get specific closing reason by id from the organisation.", "tags": [ "Closing Reason" ], "parameters": [ { "in": "path", "name": "reasonId", "schema": { "type": "string" }, "required": true, "description": "uuid to identify the closing reason.", "example": "-poOAPBa-jFZA_AWV3zN0" } ], "responses": { "200": { "description": "Returns the closing reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClosingReason" }, "example": { "id": "-poOAPBa-jFZA_AWV3zN0", "title": "Closing due to example reason", "status": "ACTIVE", "lastUpdateTime": "2021-08-04T21:13:50.373Z", "creationTime": "2021-08-04T21:13:50.373Z" } } } }, "400": { "description": "Validation Errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } }, "401": { "description": "Authentication Errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } }, "404": { "description": "Closing reason not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClosingReasonNotFoundResp" } } } }, "500": { "description": "Other errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } } } }, "patch": { "operationId": "changeReasonStatus", "summary": "changeReasonStatus", "description": "Change the status of a Closing Reason (eg. ACTIVE to INACTIVE).", "tags": [ "Closing Reason" ], "parameters": [ { "in": "path", "name": "reasonId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "change the status of a closing reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeReasonStatusReq" } } } }, "responses": { "202": { "description": "The status change was accepted" }, "400": { "description": "bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResp" } } } } } } }, "/v1/workflows/definitions/{definitionId}/closing-reasons": { "get": { "operationId": "getWorkflowClosingReasons", "summary": "getWorkflowClosingReasons", "description": "Returns all closing reasons defined for the workflow.", "parameters": [ { "in": "path", "name": "definitionId", "schema": { "type": "string" }, "required": true, "description": "ID of a workflow definition", "example": "fxcwfw" } ], "tags": [ "Workflows" ], "responses": { "200": { "description": "Returns the entire catalog of closing reasons for a specific workflow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClosingReasonsIds" } } } } } }, "patch": { "operationId": "setWorkflowClosingReasons", "summary": "setWorkflowClosingReasons", "description": "Sets which closing reasons are defined for this workflow, based on the entire closing reasons catalog.", "tags": [ "Workflows" ], "parameters": [ { "in": "path", "name": "definitionId", "schema": { "type": "string" }, "required": true, "description": "ID of a workflow definition", "example": 7889 } ], "requestBody": { "description": "set all closing reasons for a specific definition", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClosingReasonsIds" } } } }, "responses": { "201": { "description": "closing reasons are set for this workflow" } } } } }, "components": { "parameters": { "EnforceLimitsParam": { "in": "query", "name": "enforce_limits", "required": false, "schema": { "type": "boolean", "default": false }, "description": "When true, size/count limit violations (max incoming edges per task, max branches, max entity-sync rules, ...) are enforced as 400 errors. Used by the flow-builder UI for interactive authoring. On update, pre-existing violations are tolerated as long as the request does not worsen them. When false or absent (default for API/system callers such as blueprints, configuration hub and snapshots), limit violations are accepted and returned as `limit_warnings`. Structural errors are always enforced regardless of this flag." } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "FlowTemplateBase": { "type": "object", "description": "Base schema for V2 flow templates. A flow template defines the structure of a workflow\nincluding phases, tasks, edges, triggers, and other configuration. Flow templates serve\nas blueprints that can be instantiated as flow executions.\n", "required": [ "name", "tasks", "edges" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the flow template, generated by the system." }, "org_id": { "type": "string", "description": "Organization identifier that owns this flow template." }, "name": { "type": "string", "description": "Display name for the workflow, shown to users in the UI.", "minLength": 3 }, "description": { "type": "string", "description": "Optional detailed description of the workflow's purpose and behavior.", "maxLength": 5000 }, "trigger": { "$ref": "#/components/schemas/Trigger" }, "enabled": { "type": "boolean", "description": "Whether the workflow is enabled or not", "default": true }, "version": { "$ref": "#/components/schemas/Version" }, "created_at": { "type": "string", "description": "ISO String Date & Time", "example": "2021-04-27T12:01:13.000Z" }, "updated_at": { "type": "string", "description": "ISO String Date & Time", "example": "2021-04-27T12:01:13.000Z" }, "due_date": { "type": "string", "example": "2021-04-27T12:00:00.000Z" }, "due_date_config": { "$ref": "#/components/schemas/DueDateConfig" }, "assigned_to": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/VariableAssignment" } ] } }, "available_in_ecp": { "type": "boolean", "description": "Indicates whether this workflow is available for End Customer Portal or not. By default it's not." }, "additional_triggers": { "type": "array", "description": "Additional trigger configurations that can also start this flow. Useful for flows that should be startable via multiple methods (e.g., both automation AND manual).", "items": { "$ref": "#/components/schemas/Trigger" } }, "phases": { "type": "array", "items": { "$ref": "#/components/schemas/Phase" } }, "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } }, "edges": { "type": "array", "items": { "$ref": "#/components/schemas/Edge" } }, "closing_reasons": { "type": "array", "items": { "$ref": "#/components/schemas/ClosingReason" } }, "entity_sync": { "type": "array", "items": { "$ref": "#/components/schemas/EntitySync" } }, "taxonomies": { "type": "array", "items": { "type": "string" }, "description": "Taxonomy ids that are associated with this workflow and used for filtering" }, "singleClosingReasonSelection": { "type": "boolean", "description": "Whether only a single closing reason can be selected" }, "_manifest": { "type": "array", "description": "The manifest IDs associated with this workflow", "items": { "type": "string" } }, "linear": { "type": "boolean", "description": "When true, this is a linear flow: task enablement is computed at runtime from the graph — a task is enabled only when all of its direct predecessor tasks in its branch are done. This fully overrides any explicit per-task requirements." }, "limit_warnings": { "type": "array", "description": "Non-blocking warnings for configuration limits the flow exceeds. Returned on read (get-flow) and on create/update responses. Size/count limits are soft: a flow exceeding them is still accepted and stored, and the violations are reported here so the UI can surface an informational banner. The flow is still fully editable and usable.", "items": { "$ref": "#/components/schemas/FlowLimitWarning" } } } }, "FlowLimitWarning": { "type": "object", "description": "A configuration limit that the flow currently exceeds. Returned by the get-flow endpoint and by create/update responses so the UI can show a non-blocking banner. Size/count limit violations never cause a 400 — only structural errors do. The flow remains fully usable; users are encouraged to bring values within the limits.", "required": [ "i18nKey", "message", "max", "path" ], "properties": { "i18nKey": { "type": "string", "description": "i18n key identifying the exceeded limit (e.g. errors.task_max_incoming_edges)." }, "message": { "type": "string", "description": "Human-readable description of the exceeded limit." }, "max": { "type": "number", "description": "The configured maximum for this limit." }, "current": { "type": "number", "description": "The actual value the flow currently has for this limit (e.g. the actual number of incoming connections)." }, "node_id": { "type": "string", "description": "ID of the task/node the limit applies to, when applicable." }, "task_name": { "type": "string" }, "branch_name": { "type": "string" }, "param_name": { "type": "string", "description": "Name of the AI-agent parameter the limit applies to, when applicable." }, "path": { "type": "array", "items": {}, "description": "JSON path within the flow to the offending value." } } }, "FlowTemplate": { "allOf": [ { "$ref": "#/components/schemas/FlowTemplateBase" }, { "type": "object", "properties": { "closing_reasons": { "type": "array", "items": { "$ref": "#/components/schemas/ClosingReason" } } } } ] }, "Version": { "type": "string", "enum": [ "v1", "v2", "v3" ], "description": "Version of the workflow schema.\n\n- `v1` – *Deprecated*. The initial version of workflows with limited structure and automation capabilities.\n- `v2` – Linear workflows. Supports sequential task execution with basic automation triggers.\n- `v3` – Advanced workflows. Adds support for branching logic (conditions), parallel paths, and enhanced automation features such as dynamic triggers and flow control.\n", "example": 2 }, "Trigger": { "anyOf": [ { "$ref": "#/components/schemas/ManualTrigger" }, { "$ref": "#/components/schemas/AutomationTrigger" }, { "$ref": "#/components/schemas/JourneySubmissionTrigger" }, { "$ref": "#/components/schemas/JourneyAutomationTrigger" } ], "example": { "type": "automation", "automation_id": "g92j2-sg9ug92hjt1gh-9s9gajgs-a979gg" } }, "ManualTrigger": { "type": "object", "required": [ "type" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "manual" ] }, "entity_schema": { "type": "string" } } }, "AutomationTrigger": { "type": "object", "required": [ "type" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "automation" ] }, "automation_id": { "type": "string", "description": "Id of the automation config that triggers this workflow" }, "input_entity": { "type": "string", "enum": [ "thread", "first_email", "last_email" ], "description": "For email thread triggers, specifies which entity from the triggered email thread to use as the primary input for automation and decision tasks. Defaults to `thread` when not specified.\n" }, "trigger_config": { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The trigger type (e.g. entity_operation, activity)" }, "configuration": { "type": "object", "additionalProperties": true, "description": "Trigger-specific configuration" } }, "additionalProperties": true }, "description": "Transient field. Trigger configurations for creating or updating the trigger automation flow. Each item follows the automation API trigger schema. Processed by the backend during create/update and stripped before storage.\n" } } }, "JourneyAutomationTrigger": { "type": "object", "required": [ "type" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "journey_automation" ] }, "entity_schema": { "type": "string", "description": "Schema of the main entity where flow will be triggered. The entity will be picked from automation context." } } }, "JourneySubmissionTrigger": { "type": "object", "required": [ "type", "journey_id" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "journey_submission" ] }, "journey_id": { "type": "string", "description": "ID of the journey that will trigger this flow" }, "journey_name": { "type": "string", "description": "Name of the journey that will trigger this flow" }, "automation_id": { "type": "string" } } }, "CreateFlowTemplate": { "allOf": [ { "$ref": "#/components/schemas/FlowTemplateBase" }, { "type": "object", "properties": { "closing_reasons": { "type": "array", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" } } } } } } ] }, "SearchFlowTemplates": { "type": "object", "properties": { "name": { "type": "string" }, "definition_id": { "type": "string" }, "trigger_type": { "type": "string", "enum": [ "journey_submission", "manual", "automation" ] }, "enabled": { "type": "boolean" }, "from": { "type": "integer" }, "size": { "type": "integer" }, "sort_by": { "type": "string", "enum": [ "created_at", "updated_at" ], "default": "updated_at" }, "sort_order": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } } }, "FlowTemplatesList": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/FlowTemplate" } } }, "required": [ "results" ] }, "FlowTemplateId": { "type": "string", "description": "Short unique id (length 8) to identify the Flow Template.", "example": "7hj28akg" }, "Task": { "anyOf": [ { "$ref": "#/components/schemas/ManualTask" }, { "$ref": "#/components/schemas/AutomationTask" }, { "$ref": "#/components/schemas/DecisionTask" }, { "$ref": "#/components/schemas/AiAgentTask" } ] }, "ManualTask": { "allOf": [ { "$ref": "#/components/schemas/TaskBase" } ] }, "AutomationTask": { "allOf": [ { "$ref": "#/components/schemas/TaskBase" }, { "type": "object", "required": [ "automation_config" ], "properties": { "automation_config": { "$ref": "#/components/schemas/AutomationConfig" }, "trigger_mode": { "$ref": "#/components/schemas/TriggerMode" }, "schedule": { "$ref": "#/components/schemas/ActionSchedule" }, "created_automatically": { "type": "boolean", "description": "Indicates whether this task was created automatically by journeys or manually by an user", "default": false } } } ] }, "AutomationConfig": { "type": "object", "description": "Configuration for automation execution to run", "properties": { "flow_id": { "type": "string", "description": "Id of the configured automation to run" }, "action_config": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The action type (e.g. send-email, trigger-workflow)" }, "config": { "type": "object", "additionalProperties": true, "description": "Action-specific configuration" } }, "additionalProperties": true, "description": "Transient field. The full automation action configuration following the automation API action schema. Processed by the backend during create/update and stripped before storage. When present without a flow_id, a new automation flow is created. When present with a flow_id, the existing automation flow is updated.\n" }, "duplicated_flow_id": { "type": "string", "description": "Transient field. When present, the backend clones the automation flow referenced by this ID and assigns the new flow_id to the task. Used when duplicating an automation task to give it an independent automation. Stripped before storage.\n" }, "input_context": { "$ref": "#/components/schemas/AutomationInputContext" } } }, "AutomationInputContext": { "type": "object", "description": "Optional. Source of the entity fed into this automation task. If omitted, the workflow's primary entity is used.\n", "required": [ "source" ], "properties": { "source": { "type": "string", "enum": [ "trigger", "task" ], "description": "`trigger` = workflow's primary (trigger) entity. `task` = entity produced by an upstream task in the graph.\n" }, "task_id": { "type": "string", "description": "Required when source is `task`. The id of the upstream task whose output entity should feed this task." } } }, "AiAgentTask": { "allOf": [ { "$ref": "#/components/schemas/TaskBase" }, { "type": "object", "properties": { "agent_config": { "$ref": "#/components/schemas/AgentConfig" } } } ] }, "AgentConfig": { "type": "object", "description": "Configuration for AI Agent to run", "required": [ "agent_id" ], "properties": { "agent_id": { "type": "string", "description": "Id of the configured AI Agent to run" } }, "additionalProperties": true }, "TriggerMode": { "type": "string", "enum": [ "manual", "automatic" ] }, "ActionSchedule": { "anyOf": [ { "$ref": "#/components/schemas/ImmediateSchedule" }, { "$ref": "#/components/schemas/DelayedSchedule" }, { "$ref": "#/components/schemas/RelativeSchedule" } ] }, "ImmediateSchedule": { "type": "object", "properties": { "mode": { "enum": [ "immediate" ] } } }, "DelayedSchedule": { "type": "object", "required": [ "mode", "duration", "unit" ], "properties": { "mode": { "enum": [ "delayed" ] }, "duration": { "type": "number", "minimum": 1 }, "unit": { "$ref": "#/components/schemas/TimeUnit" } } }, "RelativeSchedule": { "type": "object", "properties": { "mode": { "enum": [ "relative" ] }, "direction": { "type": "string", "enum": [ "before", "after" ] }, "duration": { "type": "number", "minimum": 1 }, "unit": { "$ref": "#/components/schemas/TimeUnit" }, "reference": { "type": "object", "required": [ "id", "origin" ], "properties": { "id": { "type": "string", "description": "The id of the entity / workflow / task, based on the origin of the schedule. For all_preceding_tasks_completed, use the sentinel value \"all_preceding_tasks_completed\"." }, "origin": { "type": "string", "enum": [ "flow_started", "task_completed", "trigger_entity_attribute", "all_preceding_tasks_completed" ] }, "schema": { "type": "string", "description": "The schema of the entity" }, "attribute": { "type": "string", "description": "An entity attribute that identifies a date / datetime" } } } }, "required": [ "mode", "direction", "duration", "unit", "reference" ] }, "DecisionTask": { "allOf": [ { "$ref": "#/components/schemas/TaskBase" }, { "type": "object", "properties": { "trigger_mode": { "$ref": "#/components/schemas/TriggerMode" }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/Condition" } }, "allow_parallel_execution": { "type": "boolean", "description": "When true, all branches with met conditions execute in parallel. When false, only the first branch with a met condition is executed. Defaults to true for backwards compatibility.", "default": true }, "schedule": { "anyOf": [ { "$ref": "#/components/schemas/DelayedSchedule" }, { "$ref": "#/components/schemas/RelativeSchedule" } ] }, "loop_config": { "type": "object", "properties": { "loop_branch_id": { "type": "string", "description": "The id of the branch that will be looped" }, "exit_branch_id": { "type": "string", "description": "The id of the branch that will be used to exit the loop" }, "max_iterations": { "type": "integer", "description": "Maximum number of iterations for the loop branch", "default": 3, "minimum": 1 } }, "required": [ "loop_branch_id", "exit_branch_id", "max_iterations" ] } }, "required": [ "trigger_mode", "conditions" ] } ] }, "TaskBase": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "$ref": "#/components/schemas/StepDescription" }, "journey": { "$ref": "#/components/schemas/StepJourney" }, "due_date": { "type": "string", "example": "2021-04-27T12:00:00.000Z" }, "due_date_config": { "$ref": "#/components/schemas/DueDateConfig" }, "requirements": { "type": "array", "description": "requirements that need to be fulfilled in order to enable the task while flow instances are running", "items": { "$ref": "#/components/schemas/EnableRequirement" } }, "assigned_to": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/VariableAssignment" } ] } }, "ecp": { "$ref": "#/components/schemas/ECPDetails" }, "installer": { "$ref": "#/components/schemas/ECPDetails" }, "partner": { "$ref": "#/components/schemas/PartnerDetails", "description": "Partner-specific task details shown to partner org users viewing shared resources" }, "taxonomies": { "type": "array", "items": { "type": "string" }, "description": "Taxonomy ids that are associated with this workflow and used for filtering" }, "phase_id": { "type": "string" }, "task_type": { "$ref": "#/components/schemas/TaskType" } }, "required": [ "id", "name", "task_type" ] }, "Phase": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "due_date": { "type": "string", "example": "2021-04-27T12:00:00.000Z" }, "due_date_config": { "$ref": "#/components/schemas/DueDateConfig" }, "assigned_to": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/VariableAssignment" } ] } }, "taxonomies": { "type": "array", "items": { "type": "string" }, "description": "Taxonomy ids that are associated with this workflow and used for filtering" } }, "required": [ "id", "name" ] }, "VariableAssignment": { "type": "object", "description": "Represents a variable assignment with its expression and optional resolved value. Used for dynamic user assignments that get resolved during workflow execution.", "properties": { "variable": { "type": "string", "description": "The variable expression, e.g., \"{{entity.owner}}\"", "example": "{{entity.owner}}" }, "value": { "type": "array", "items": { "type": "string" }, "description": "The resolved values after variable evaluation (populated during execution)", "example": [ "user_12345" ] } }, "required": [ "variable" ] }, "TaskType": { "type": "string", "enum": [ "MANUAL", "AUTOMATION", "DECISION", "AI_AGENT" ] }, "Edge": { "type": "object", "properties": { "id": { "type": "string" }, "from_id": { "type": "string" }, "to_id": { "type": "string", "nullable": true }, "condition_id": { "type": "string" }, "none_met": { "type": "boolean", "description": "Indicates a default case for a decision task. Only decision task edges can have this field and the flow advances using this edge if no conditions are met." } }, "required": [ "id", "from_id" ] }, "Condition": { "type": "object", "properties": { "id": { "type": "string" }, "branch_name": { "type": "string", "description": "The name of the branch", "example": "Branch 1" }, "logical_operator": { "type": "string", "enum": [ "AND", "OR" ] }, "statements": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/Statement" } } }, "required": [ "id", "branch_name", "logical_operator", "statements" ] }, "Statement": { "type": "object", "properties": { "id": { "type": "string" }, "source": { "$ref": "#/components/schemas/EvaluationSource" }, "operator": { "$ref": "#/components/schemas/Operator" }, "values": { "type": "array", "items": { "type": "string" } }, "value_type": { "type": "string", "enum": [ "static", "relative_date" ], "description": "How to interpret values. \"static\" (default) means literal values. \"relative_date\" means values[0] is a dynamic date token like \"today\"." } }, "required": [ "id", "source", "operator", "values" ] }, "EvaluationSource": { "type": "object", "properties": { "id": { "type": "string", "description": "The id of the action or trigger" }, "origin": { "type": "string", "enum": [ "trigger", "action" ] }, "origin_type": { "type": "string", "enum": [ "entity", "workflow", "journey_block" ] }, "schema": { "type": "string" }, "attribute": { "type": "string" }, "attribute_type": { "type": "string", "enum": [ "string", "text", "number", "boolean", "date", "datetime", "tags", "country", "email", "phone", "product", "price", "status", "relation", "multiselect", "select", "radio", "relation_user", "purpose", "label", "message_email_address" ] }, "attribute_repeatable": { "type": "boolean" }, "attribute_operation": { "enum": [ "all", "updated", "added", "deleted" ] }, "attributes": { "type": "array", "maxItems": 10, "items": { "type": "string" }, "description": "Multi-attribute mode. When present and length > 1, the statement is\nevaluated against every listed attribute and combined via\n`attributes_match`. All listed attributes must share the same\n`attribute_type`. Mutually exclusive with `attribute_sub_field`,\n`date_offset`, and `attribute_operation`. When absent or length === 1,\nthe legacy `attribute` field is used.\n" }, "attributes_match": { "type": "string", "enum": [ "any", "all" ], "description": "Inner connector across `attributes`. `any` (default) means at least\none attribute must satisfy the operator; `all` means every attribute\nmust satisfy it. Ignored when `attributes` is absent or has length < 2.\n" }, "attribute_sub_field": { "type": "string", "description": "For complex attribute types, specifies which sub-field to extract (e.g., \"address\", \"name\", \"email_type\")" }, "date_offset": { "type": "object", "description": "Offset to apply to the source date value before comparison (e.g., +18 years for age check, +30 days for expiry)", "properties": { "amount": { "type": "integer", "description": "Number of units to offset" }, "unit": { "type": "string", "enum": [ "days", "months", "years" ], "description": "Unit of the offset" } } } } }, "Operator": { "type": "string", "enum": [ "equals", "not_equals", "any_of", "none_of", "contains", "not_contains", "starts_with", "ends_with", "greater_than", "less_than", "greater_than_or_equals", "less_than_or_equals", "is_empty", "is_not_empty" ] }, "DueDateConfig": { "description": "Set due date for the task based on a dynamic condition", "type": "object", "properties": { "duration": { "type": "number" }, "unit": { "$ref": "#/components/schemas/TimeUnit" }, "type": { "type": "string", "enum": [ "WORKFLOW_STARTED", "TASK_FINISHED", "PHASE_FINISHED", "A_PRECEDING_TASK_COMPLETED", "ALL_PRECEDING_TASKS_COMPLETED" ] }, "task_id": { "type": "string" }, "phase_id": { "type": "string" } }, "required": [ "duration", "unit", "type" ] }, "TimeUnit": { "type": "string", "enum": [ "minutes", "hours", "days", "weeks", "months", "years" ] }, "EnableRequirement": { "description": "describe the requirement for a task to be enabled", "type": "object", "properties": { "task_id": { "type": "string", "description": "The id of the task that it points to" }, "phase_id": { "type": "string", "description": "The id of the phase that it points to" }, "when": { "type": "string", "enum": [ "TASK_FINISHED", "PHASE_FINISHED" ] } }, "required": [ "when" ] }, "WorkflowDefinition": { "type": "object", "description": "V1 workflow definition schema. Defines a linear workflow structure with sections\nand steps. Sections group related steps together, and steps represent individual\ntasks that need to be completed. This is the legacy workflow model; for new\nimplementations, consider using V2 flow templates instead.\n", "properties": { "id": { "type": "string", "description": "Unique identifier for the workflow definition, generated by the system." }, "name": { "type": "string", "description": "Display name for the workflow, shown to users in the UI." }, "description": { "type": "string", "description": "Optional detailed description of the workflow's purpose and behavior." }, "creationTime": { "type": "string", "description": "ISO String Date & Time", "example": "2021-04-27T12:01:13.000Z" }, "enabled": { "type": "boolean", "description": "Whether the workflow is enabled or not", "default": true }, "lastUpdateTime": { "type": "string", "description": "ISO String Date & Time", "example": "2021-04-27T12:01:13.000Z" }, "dueDate": { "type": "string", "example": "2021-04-27T12:00:00.000Z" }, "dynamicDueDate": { "$ref": "#/components/schemas/DynamicDueDate" }, "userIds": { "type": "array", "items": { "type": "number" }, "deprecated": true, "description": "This field is deprecated. Please use assignedTo" }, "assignedTo": { "type": "array", "items": { "type": "string" } }, "enableECPWorkflow": { "type": "boolean", "description": "Indicates whether this workflow is available for End Customer Portal or not. By default it's not." }, "flow": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/Section" }, { "$ref": "#/components/schemas/Step" } ] } }, "closingReasons": { "type": "array", "items": { "$ref": "#/components/schemas/ClosingReasonId" } }, "updateEntityAttributes": { "type": "array", "items": { "$ref": "#/components/schemas/UpdateEntityAttributes" } }, "taxonomies": { "type": "array", "items": { "type": "string" }, "description": "Taxonomy ids that are associated with this workflow and used for filtering" }, "singleClosingReasonSelection": { "type": "boolean", "description": "Whether only a single closing reason can be selected" }, "_manifest": { "type": "array", "description": "The manifest IDs associated with this workflow", "items": { "type": "string" } } }, "required": [ "name", "flow" ] }, "Step": { "type": "object", "description": "Action that needs to be done in a Workflow", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "$ref": "#/components/schemas/StepDescription" }, "executionType": { "$ref": "#/components/schemas/StepType" }, "automationConfig": { "type": "object", "properties": { "flowId": { "type": "string", "description": "Id of the configured automation to run" } }, "required": [ "flowId" ] }, "journey": { "$ref": "#/components/schemas/StepJourney" }, "order": { "type": "number" }, "dueDate": { "type": "string", "example": "2021-04-27T12:00:00.000Z" }, "dynamicDueDate": { "$ref": "#/components/schemas/DynamicDueDate" }, "userIds": { "type": "array", "items": { "type": "number" }, "deprecated": true, "description": "This field is deprecated. Please use assignedTo" }, "requirements": { "type": "array", "description": "requirements that need to be fulfilled in order to enable the step execution", "items": { "$ref": "#/components/schemas/StepRequirement" } }, "assignedTo": { "type": "array", "items": { "type": "string" } }, "type": { "$ref": "#/components/schemas/ItemType" }, "ecp": { "$ref": "#/components/schemas/ECPDetails" }, "installer": { "$ref": "#/components/schemas/ECPDetails" }, "partner": { "$ref": "#/components/schemas/PartnerDetails", "description": "Partner-specific task details shown to partner org users viewing shared resources" }, "taxonomies": { "type": "array", "items": { "type": "string" }, "description": "Taxonomy ids that are associated with this workflow and used for filtering" } }, "required": [ "name", "order", "type" ] }, "Section": { "type": "object", "description": "A group of Steps that define the progress of the Workflow", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "order": { "type": "number" }, "type": { "$ref": "#/components/schemas/ItemType" }, "dueDate": { "type": "string", "example": "2021-04-27T12:00:00.000Z" }, "dynamicDueDate": { "$ref": "#/components/schemas/DynamicDueDate" }, "assignedTo": { "type": "array", "items": { "type": "string" } }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/Step" } }, "taxonomies": { "type": "array", "items": { "type": "string" }, "description": "Taxonomy ids that are associated with this workflow and used for filtering" } }, "required": [ "name", "order", "type", "steps" ] }, "TriggerType": { "type": "string", "enum": [ "MANUAL", "AUTOMATIC" ] }, "ItemType": { "type": "string", "enum": [ "STEP", "SECTION" ] }, "StepType": { "type": "string", "enum": [ "MANUAL", "AUTOMATION" ] }, "StepJourney": { "type": "object", "properties": { "id": { "type": "string" }, "journeyId": { "type": "string" }, "name": { "type": "string" }, "complete_task_automatically": { "type": "boolean", "default": true, "description": "If true, the task be auto completed when the journey is completed. By default it is true." } } }, "ECPDetails": { "type": "object", "description": "Details regarding ECP for the workflow step", "properties": { "enabled": { "type": "boolean" }, "label": { "type": "string" }, "description": { "type": "string" }, "journey": { "$ref": "#/components/schemas/StepJourney" } } }, "PartnerDetails": { "type": "object", "description": "Details regarding partner for the workflow step", "properties": { "enabled": { "type": "boolean" }, "label": { "type": "string" }, "description": { "type": "string" } } }, "StepDescription": { "type": "object", "description": "Longer information regarding Task", "properties": { "enabled": { "type": "boolean" }, "value": { "type": "string", "maxLength": 10000 } } }, "MaxAllowedLimit": { "type": "object", "properties": { "currentNoOfWorkflows": { "type": "number" }, "maxAllowed": { "type": "number" } } }, "DefinitionNotFoundResp": { "type": "object", "description": "Error response returned when a workflow definition or flow template is not found.", "properties": { "message": { "type": "string", "description": "Human-readable message indicating the resource was not found.", "example": "Definition with id 'abc123' not found" } } }, "ClosingReasonNotFoundResp": { "type": "object", "description": "Error response returned when a closing reason is not found.", "properties": { "message": { "type": "string", "description": "Human-readable message indicating the closing reason was not found.", "example": "Closing reason with id 'xyz789' not found" } } }, "ChangeReasonStatusReq": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/ClosingReasonsStatus" } }, "required": [ "status" ] }, "ClosingReasons": { "type": "object", "properties": { "reasons": { "type": "array", "items": { "$ref": "#/components/schemas/ClosingReason" } } }, "required": [ "reasons" ] }, "ClosingReason": { "type": "object", "description": "One Closing reason for a workflow", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "status": { "$ref": "#/components/schemas/ClosingReasonsStatus" }, "lastUpdateTime": { "type": "string", "readOnly": true }, "creationTime": { "type": "string", "readOnly": true } } }, "ClosingReasonsStatus": { "type": "string", "enum": [ "ACTIVE", "INACTIVE" ] }, "ClosingReasonsIds": { "type": "object", "properties": { "reasons": { "type": "array", "items": { "$ref": "#/components/schemas/ClosingReasonId" } } }, "required": [ "reasons" ] }, "ClosingReasonId": { "type": "object", "properties": { "id": { "type": "string", "example": "x739cew" } }, "required": [ "id" ] }, "ErrorResp": { "type": "object", "description": "Standard error response returned when an API request fails.", "properties": { "message": { "type": "string", "description": "Human-readable error message describing what went wrong.", "example": "Invalid request body: name is required" } } }, "UpdateEntityAttributes": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "workflow_status", "current_section", "current_step" ] }, "target": { "type": "object", "properties": { "entitySchema": { "type": "string", "example": "opportunity" }, "entityAttribute": { "type": "string", "example": "my_status" } }, "required": [ "entitySchema", "entityAttribute" ] } }, "required": [ "source", "target" ] }, "EntitySync": { "type": "object", "properties": { "trigger": { "type": "object", "description": "Trigger configuration that determines when entity sync occurs.\nContains the event type and optional filter to target specific tasks/phases.\n", "required": [ "event" ], "properties": { "event": { "type": "string", "description": "Event or condition that triggers the entity sync.\nDirect triggers match EventBridge event names (PascalCase).\nStatus triggers are deduced from event + entity status combination.\n", "enum": [ "FlowStarted", "FlowCompleted", "FlowCancelled", "FlowReopened", "FlowDeleted", "FlowAssigned", "FlowDueDateChanged", "FlowContextsChanged", "TaskUpdated", "CurrTaskChanged", "TaskCompleted", "TaskSkipped", "TaskMarkedInProgress", "TaskMarkedOnHold", "PhaseUpdated", "PhaseCompleted", "PhaseSkipped", "PhaseMarkedInProgress" ] }, "filter": { "type": "object", "description": "Optional filter to target specific tasks or phases.\nSpecify either task_template_id OR phase_template_id (mutually exclusive).\nIf omitted, trigger applies to all tasks/phases.\n", "properties": { "task_template_id": { "type": "string", "description": "Target a specific task by its template ID (stable across executions)" }, "phase_template_id": { "type": "string", "description": "Target a specific phase by its template ID (stable across executions)" } } } } }, "value": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "workflow_name", "workflow_status", "workflow_assigned_to", "task_name", "task_status", "task_assigned_to", "phase_name", "phase_status", "phase_assigned_to", "custom_value" ] }, "value": { "type": "string" } }, "required": [ "source" ] }, "target": { "type": "object", "properties": { "entitySchema": { "type": "string", "example": "opportunity" }, "entityAttribute": { "type": "string", "example": "title" } }, "required": [ "entitySchema", "entityAttribute" ] } }, "example": { "trigger": { "event": "FlowStarted" }, "target": { "entitySchema": "opportunity", "entityAttribute": "title" }, "value": { "source": "workflow_name" } }, "required": [ "trigger", "target", "value" ] }, "DynamicDueDate": { "description": "Configuration for calculating a due date dynamically based on workflow events.\nThe due date is computed by adding a duration (numberOfUnits + timePeriod) to\na reference point defined by actionTypeCondition (e.g., when workflow started,\nwhen a step closed, or when a phase finished).\n", "type": "object", "properties": { "numberOfUnits": { "type": "number", "description": "Number of time units to add to the reference point." }, "timePeriod": { "$ref": "#/components/schemas/TimeUnit" }, "actionTypeCondition": { "type": "string", "enum": [ "WORKFLOW_STARTED", "STEP_CLOSED", "PHASE_FINISHED" ] }, "stepId": { "type": "string" }, "phaseId": { "type": "string" } }, "required": [ "numberOfUnits", "timePeriod", "actionTypeCondition" ] }, "StepRequirement": { "description": "describe the requirement for step enablement", "type": "object", "properties": { "definitionId": { "type": "string" }, "type": { "$ref": "#/components/schemas/ItemType" }, "condition": { "type": "string", "enum": [ "CLOSED" ] } }, "required": [ "definitionId", "type", "condition" ] } } }, "servers": [] }