Initiate Workflow Action

Initiate a workflow action on a specific workflow.

POST/api/{version}/objects/objectworkflows/{workflow_id}/actions/{workflow_action}

Headers

Name	Description
`Content-Type`	`application/json` (default) or `application/x-www-form-urlencoded`
`Accept`	`application/json` (default) or `application/xml`

URI Path Parameters

Name	Description
`{workflow_id}`	The workflow `id` field value.
`{workflow_action}`	The workflow action name retrieved from Retrieve Workflow Actions.

Body Parameters

In the body of the request, add any fields required to initiate the action. These will differ depending on your specified {workflow_action}. For more information about fields required for an action, Retrieve Workflow Action Details. The following tables show common workflow actions in Vault, but there may be other actions which are not listed here.

Replace Workflow Owner: replaceworkflowowner

Name	Description
`new_workflow_owner` required	The `id` of the user who will become the new workflow owner, in the format `user:{id}`. For example, `user:6014`.

Email Workflow Participants: emailparticipants

Name	Description
`email_recipients` required	A comma-delimited list of email recipients or groups, in the format `user:{user_id}` and `group:{group_label}`. For example, `user:1082,user:4802,group:incompleteTaskOwners,user:3582`. To find available `{group_label}`s, Retrieve Workflow Action Details for `emailparticipants`. If a user is not a potential recipient based on their task status, the user will not receive an email.
`email_message` required	The body of the email message to send to users. Maximum 5,000 characters.
`send_copy_to_self` optional	Set to `true` to send a copy of the email to the authenticated user. If omitted, defaults to `false`.

Add Participants: addparticipants

Name	Description
`participants` required	The `id` of the user to add as a participant, in the format `user:{id}`. For example, `user:1006`.

Remove Documents from Envelope: removecontent

Name	Description
`contents__sys` required	The `id` of the document to remove from the workflow. To remove multiple documents, use a comma-separated list of `id`s.

Update Workflow Due Date: updateworkflowduedate

This action changes the current workflow due date to a new date. Only available on workflows already configured with a workflow due date.

Name	Description
`workflow_due_date` required	The new due date for the workflow, in the format `YYYY-MM-DD`.

Replace Participants: replaceparticipants

To replace participants in an active workflow, you cannot use this endpoint. Instead, use:

Remove Participants: removeparticipants

To remove participants in an active workflow, you cannot use this endpoint. Instead, use:

Request

curl -X POST -H "Authorization: {AUTH_VALUE}" \
-H "Content-Type: application/json" \
https://myvault.veevavault.com/api/v26.3/objects/objectworkflows/801/actions/cancel

Response

{
    "responseStatus": "SUCCESS"
}

Response Details

If the {workflow_action} executes successfully, the response returns SUCCESS. For example, the cancel workflow action. On FAILURE, the response returns an error type and message describing the reason for the failure. For example, the API returns INVALID_DATA if a user or group cannot be added as a workflow participant because they are not in the appropriate role.