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

authorizationbearer [ACCESS_TOKEN]

content-typeapplication/json

Path Parameters

workflow_id stringin pathrequired

example12345

The ID of the workflow.

Request Body

type stringin bodyoptional

example"workflow_parameters"

The type of the parameters object

Value is always workflow_parameters

files object arrayin bodyrequired

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

[files].id stringin bodyoptional

example"12345678"

The id of the file

[files].type stringin bodyoptional

example"file"

The type of the file object

Value is always file

flow objectin body

The flow that will be triggered

flow.id stringin bodyrequired

example"123456789"

The id of the flow

flow.type stringin bodyrequired

example"flow"

The type of the flow object

folder objectin body

The folder object for which the workflow is configured.

folder.id stringin bodyrequired

example"87654321"

The id of the folder

folder.type stringin bodyrequired

example"folder"

The type of the folder object

Value is always folder

outcomes object arrayin bodyoptional

A configurable outcome the workflow should complete.

[outcomes].id stringin bodyconditionally required

example"17363629"

ID of a specific outcome

[outcomes].collaborators objectin body

Lists collaborators affected by the workflow result.

collaborators.type stringin bodyoptional

example"variable"

Collaborator object type.

Value is always variable

collaborators.variable_type stringin bodyoptional

example"user_list"

Variable type for the Collaborator object.

Value is always user_list

collaborators.variable_value object arrayin bodyoptional

A list of user IDs.

[variable_value].id stringin bodyconditionally required

example"636281"

User's ID.

[variable_value].type stringin bodyconditionally required

example"user"

The object type.

Value is always user

[outcomes].completion_rule objectin body

Determines if an action should be completed by all or any assignees.

completion_rule.type stringin bodyoptional

example"variable"

Completion Rule object type.

Value is always variable

completion_rule.variable_type stringin bodyoptional

example"task_completion_rule"

Variable type for the Completion Rule object.

Value is always task_completion_rule

completion_rule.variable_value stringin bodyoptional

example"all_assignees"

Variable values for a completion rule.

Value is one of all_assignees,any_assignees

[outcomes].file_collaborator_role objectin body

Determines if the workflow outcome for a file affects a specific collaborator role.

file_collaborator_role.type stringin bodyoptional

example"variable"

Role object type.

Value is always variable

file_collaborator_role.variable_type stringin bodyoptional

example"collaborator_role"

The variable type used by the object.

Value is always collaborator_role

file_collaborator_role.variable_value stringin bodyoptional

example"editor"

Variable values you can use for the role parameter.

Value is one of editor,viewer,previewer,uploader,previewer uploader,viewer uploader,co-owner

[outcomes].role objectin body

Determines if the workflow outcome affects a specific collaborator role.

role.type stringin bodyoptional

example"variable"

Role object type.

Value is always variable

role.variable_type stringin bodyoptional

example"collaborator_role"

The variable type used by the object.

Value is always collaborator_role

role.variable_value stringin bodyoptional

example"editor"

Variable values you can use for the role parameter.

Value is one of editor,viewer,previewer,uploader,previewer uploader,viewer uploader,co-owner

[outcomes].task_collaborators objectin body

Lists collaborators affected by the task workflow result.

task_collaborators.type stringin bodyoptional

example"variable"

Collaborator object type.

Value is always variable

task_collaborators.variable_type stringin bodyoptional

example"user_list"

Variable type for the Collaborator object.

Value is always user_list

task_collaborators.variable_value object arrayin bodyoptional

A list of user IDs.

[variable_value].id stringin bodyconditionally required

example"636281"

User's ID.

[variable_value].type stringin bodyconditionally required

example"user"

The object type.

Value is always user

Response

204none

Starts the workflow.

400application/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

403application/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

404application/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

defaultapplication/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.

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"
            }
          }
        ]
     }'

TypeScript Gen

await adminClient.workflows.startWorkflow(workflowToRun.id!, {
  type: 'workflow_parameters' as StartWorkflowRequestBodyTypeField,
  flow: {
    type: 'flow',
    id: workflowToRun.flows![0].id!,
  } satisfies StartWorkflowRequestBodyFlowField,
  files: [
    {
      type: 'file' as StartWorkflowRequestBodyFilesTypeField,
      id: workflowFileId,
    } satisfies StartWorkflowRequestBodyFilesField,
  ],
  folder: {
    type: 'folder' as StartWorkflowRequestBodyFolderTypeField,
    id: workflowFolderId,
  } satisfies StartWorkflowRequestBodyFolderField,
} satisfies StartWorkflowRequestBody);

Python Gen

admin_client.workflows.start_workflow(
    workflow_to_run.id,
    StartWorkflowFlow(type="flow", id=workflow_to_run.flows[0].id),
    [
        StartWorkflowFiles(
            type=StartWorkflowFilesTypeField.FILE.value, id=workflow_file_id
        )
    ],
    StartWorkflowFolder(
        type=StartWorkflowFolderTypeField.FOLDER.value, id=workflow_folder_id
    ),
    type=StartWorkflowType.WORKFLOW_PARAMETERS.value,
)

.NET Gen

await adminClient.Workflows.StartWorkflowAsync(workflowId: NullableUtils.Unwrap(workflowToRun.Id), requestBody: new StartWorkflowRequestBody(flow: new StartWorkflowRequestBodyFlowField() { Type = "flow", Id = NullableUtils.Unwrap(NullableUtils.Unwrap(workflowToRun.Flows)[0].Id) }, files: Array.AsReadOnly(new [] {new StartWorkflowRequestBodyFilesField() { Type = StartWorkflowRequestBodyFilesTypeField.File, Id = workflowFileId }}), folder: new StartWorkflowRequestBodyFolderField() { Type = StartWorkflowRequestBodyFolderTypeField.Folder, Id = workflowFolderId }) { Type = StartWorkflowRequestBodyTypeField.WorkflowParameters });

Swift Gen (Beta)

try await adminClient.workflows.startWorkflow(workflowId: workflowToRun.id!, requestBody: StartWorkflowRequestBody(type: StartWorkflowRequestBodyTypeField.workflowParameters, flow: StartWorkflowRequestBodyFlowField(type: "flow", id: workflowToRun.flows![0].id!), files: [StartWorkflowRequestBodyFilesField(type: StartWorkflowRequestBodyFilesTypeField.file, id: workflowFileId)], folder: StartWorkflowRequestBodyFolderField(type: StartWorkflowRequestBodyFolderTypeField.folder, id: workflowFolderId)))