Box Developer Documentation
Log in

Starts workflow based on request body

post
https://api.box.com/2.0
/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.

Request

Bearer [ACCESS_TOKEN]
application/json

Path Parameters

stringin pathrequired
"12345"

The ID of the workflow.

Request Body

stringin bodyoptional
"workflow_parameters"

The type of the parameters object

Value is always workflow_parameters

object arrayin bodyrequired

The array of files for which the workflow should start. All files must be in the workflow's configured folder.

stringin bodyoptional
"12345678"

The id of the file

stringin bodyoptional
"file"

The type of the file object

Value is always file

objectin body

The flow that will be triggered

stringin bodyrequired
"123456789"

The id of the flow

stringin bodyrequired
"flow"

The type of the flow object

objectin body

The folder object for which the workflow is configured.

stringin bodyrequired
"87654321"

The id of the folder

stringin bodyrequired
"folder"

The type of the folder object

Value is always folder

object arrayin bodyoptional

A list of outcomes required to be configured at start time.

stringin bodyoptional
"890375782"

The id of the outcome

stringin bodyoptional
"outcome"

The type of the outcome object

Value is always outcome

stringin bodyoptional
"placeholder"

This is a placeholder example for various objects that can be passed in - refer to the guides section to find out more information.

Response

none

Starts the workflow.

application/jsonClient error

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
application/jsonClient error

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
application/jsonClient error

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
application/jsonClient error

An unexpected client error.

post
Starts workflow based on request body
You can now try out some of our APIs live, right here in the documentation.
Log in

Request Example

cURL
curl -i -X POST "https://api.box.com/2.0/workflows/42037322/start" \
     -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -d '{
       "type": "workflow_parameters",
       "flow": {
        "id": "8937625", 
        "type": "flow"
       },
       "files": [{
          "type": "file",
          "id": "389047572"
        }, 
        {
          "type": "file",
          "id": "389047578"
        }],
       "folder": {
         "id": "2233212",
         "type": "folder" 
       }, 
       "outcomes": [
          {
            "id": "34895783",
            "type": "outcome",
            "task_collaborators": {
                "type": "variable",
                "variable_type": "user_list",
                "variable_value": [{ "type": "user", "id": "890273642" }]
            },
            "completion_rule": {
                "type": "variable",
                "variable_type": "task_completion_rule",
                "variable_value": "all_assignees"
            },
            "file_collaborator_role": {
                "type": "variable",
                "variable_type": "collaborator_role",
                "variable_value": "viewer"
            }
          }
        ]
     }'