Sample - Box Platform API
POST/workflows/{workflow_id}/start

Starts workflow based on request body

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.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

1 parameter · 5 body fields
workflow_idstringrequired
The ID of the workflow.
typestringoptional
The type of the parameters object.
Allowed:workflow_parameters
flowobjectrequired
The flow that will be triggered.
filesarray<object>required
The array of files for which the workflow should start. All files must be in the workflow's configured folder.
folderobjectrequired
The folder object for which the workflow is configured.
outcomesarray<Outcome>optional
A configurable outcome the workflow should complete.

5 status codes
204Starts the workflow.
400Returns 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.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
403Returns 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.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
404Returns 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.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
defaultAn unexpected client error.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.

Error handling

A 400 is returned: 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. A 403 is returned: 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. A 404 is returned: 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. Any other status is an error: An unexpected client error.