Workflows

Create, read, update and delete workflows, and read their stages, milestones and component instance history.

Workflows define the stages and milestones a record moves through. Use these endpoints to create and change workflows and to read their stages, milestones and the workflow history of custom component instances. This area has 15 endpoints, and all seven SDKs call every one.

At a glance

Endpoint	Method	Path	What it does
List workflows	GET	/workflows	Lists the workflows on your instance, one page at a time.
Retrieve a workflow	GET	/workflows/{workflow_id}	Retrieves one workflow by its wf_ id or its code.
Create a workflow	POST	/workflows	Creates a workflow as a draft and returns it.
Update a workflow	PATCH	/workflows/{workflow_id}	Changes a workflow’s fields or moves its status, and returns the workflow.
Delete a workflow	DELETE	/workflows/{workflow_id}	Deletes a workflow. Nothing comes back.
List a workflow’s stages	GET	/workflows/{workflow_id}/stages	Lists the stages of one workflow, one page at a time.
Retrieve a workflow stage	GET	/workflows/{workflow_id}/stages/{stage_id}	Retrieves one stage of a workflow by its wfs_ id.
List a workflow’s milestones	GET	/workflows/{workflow_uuid}/milestones	Lists the milestones defined on one workflow, one page at a time.
Retrieve a workflow milestone	GET	/workflows/{workflow_id}/milestones/{milestone_id}	Retrieves one milestone defined on a workflow, by its wfm_ id.
Delete a milestone	DELETE	/milestones/{milestone_uuid}	Deletes one milestone. Nothing comes back.
List a component instance’s workflow history	GET	/workflows/custom_components/{component_uuid}/{object_code}/history	Lists the workflow history of one custom component instance, one page at a time.
List a component instance’s milestones	GET	/workflows/custom_components/{component_uuid}/{object_code}/milestones	Lists the workflow milestones of one custom component instance, one page at a time.
Retrieve a component instance’s milestone	GET	/workflows/custom_components/{component_uuid}/{object_code}/milestones/{milestone_id}	Retrieves one workflow milestone of a custom component instance, by its wfmi_ id.
List a component instance’s workflow history by instance code	GET	/workflow/component/{component_object_id}/history	Lists the workflow history of one custom component instance, named by its code alone.
List a component instance’s milestones by settings uuid	GET	/workflow/component/{component_uuid}/{component_object_id}/milestone	Lists the workflow milestones of one custom component instance, named by the component’s settings uuid and the instance’s code.

Before you call

Register your API credentials once when your app starts, as shown in Authentication. Every SDK sample on these pages then gets its client in one line. With cURL, send the access token in an Authorization header: Authorization: Bearer $ACCESS_TOKEN.

Things to know

• Creates and updates are wrapped in workflow. One workflow comes back under workflow too, and name is required to create one.
• A new workflow starts as a draft. An update can move a draft to active, and move an active workflow to inactive and back.
• A workflow is read by its wf_ id or its code. The milestone listing takes the wf_ id in its workflow_uuid slot.
• Component instance routes take the component’s dashed uuid. Under /workflows/custom_components, component_uuid is the hex of the cmp_ id with the dashes put back and object_code is the instance’s code; the cmp_ id and the bare hex return 404.
• Deleting a milestone sits in this area. DELETE /milestones/{milestone_uuid} is listed with the workflow endpoints.
• Listings page by cursor. Records sit under data; pass pagination.next_cursor as cursor to read the next page, and stop when pagination.has_more is false.