---
title: "Starts workflow based on request body"
method: POST
path: "/workflows/{workflow_id}/start"
tags: ["Workflows"]
---

# Starts workflow based on request body

`POST /workflows/{workflow_id}/start`

Initiates a flow with a trigger type of `WORKFLOW_MANUAL_START`.

You application must be authorized to use the `Manage Box Relay` application
scope within the developer console.

## Path parameters

- `workflow_id` string, required

## Request body

- object
  - `type` 'workflow_parameters' — The type of the parameters object.
  - `flow` object, required — The flow that will be triggered.
    - `type` string — The type of the flow object.
    - `id` string — The id of the flow.
  - `files` object[], required — The array of files for which the workflow should start. All files must be in the workflow's configured folder.
    - `type` 'file' — The type of the file object.
    - `id` string — The id of the file.
  - `folder` object, required — The folder object for which the workflow is configured.
    - `type` 'folder' — The type of the folder object.
    - `id` string — The id of the folder.
  - `outcomes` Outcome[] — A configurable outcome the workflow should complete.
    - `id` string, required — ID of a specific outcome.
    - `collaborators` object — Lists collaborators affected by the workflow result.
      - `type` 'variable', required — Collaborator object type.
      - `variable_type` 'user_list', required — Variable type for the Collaborator object.
      - `variable_value` object[], required — A list of user IDs.
        - `type` 'user', required — The object type.
        - `id` string, required — User's ID.
    - `completion_rule` object — Determines if an action should be completed by all or any assignees.
      - `type` 'variable', required — Completion Rule object type.
      - `variable_type` 'task_completion_rule', required — Variable type for the Completion Rule object.
      - `variable_value` 'all_assignees' | 'any_assignees', required — Variable values for a completion rule.
    - `file_collaborator_role` object — Determines if the workflow outcome for a file affects a specific collaborator role.
      - `type` 'variable', required — Role object type.
      - `variable_type` 'collaborator_role', required — The variable type used by the object.
      - `variable_value` 'editor' | 'viewer' | 'previewer' | 'uploader' | 'previewer uploader' | 'viewer uploader' | 'co-owner', required — Variable values you can use for the role parameter.
    - `task_collaborators` object — Lists collaborators affected by the task workflow result.
      - `type` 'variable', required — Collaborator object type.
      - `variable_type` 'user_list', required — Variable type for the Collaborator object.
      - `variable_value` object[], required — A list of user IDs.
        - `type` 'user', required — The object type.
        - `id` string, required — User's ID.
    - `role` object — Determines if the workflow outcome affects a specific collaborator role.
      - `type` 'variable', required — Role object type.
      - `variable_type` 'collaborator_role', required — The variable type used by the object.
      - `variable_value` 'editor' | 'viewer' | 'previewer' | 'uploader' | 'previewer uploader' | 'viewer uploader' | 'co-owner', required — Variable values you can use for the role parameter.

## Response `204`

Starts the workflow.

## Other responses

- `400` — Returns an error if some of the parameters are missing or not valid. * `workflow_is_not_enabled` when the workflow is not enabled. * `workflow_not_active_on_provided_folder` when the workflow is not enabled for the specified folder id. * `parameters_provided_do_not_match_target_outcome` when the provided parameters do not match the expected parameters.
- `403` — Returns an error if there are insufficient permissions. * `insufficient_access` when the user does not have access rights to file or folder. * `missing_relay_full_access` when the user does not have access to Relay Full.
- `404` — Returns an error if the workflow could not be found, or the authenticated user does not have access to the workflow. * `workflow_not_found` when the workflow is not found. * `flow_missing_or_inaccessible` when the flow is not a manual start flow.
- `default` — An unexpected client error.

---

[API](https://skmtc.net/box/apis/platform-api.md) · [All operations](https://skmtc.net/box/apis/platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/box/platform-api/revisions/ba8f087e1a4d/schema)