Skip to content

Initiate Workflow Action

Initiate a workflow action on a specific workflow.

POST/api/{version}/objects/objectworkflows/{workflow_id}/actions/{workflow_action}
NameDescription
Content-Typeapplication/json (default) or application/x-www-form-urlencoded
Acceptapplication/json (default) or application/xml
NameDescription
{workflow_id}The workflow id field value.
{workflow_action}The workflow action name retrieved from Retrieve Workflow Actions.
NameDescription
entrycriteriaSet to true to receive a structured evaluation of entry criteria violations in the response. If omitted, defaults to false. Learn more about the entry criteria evaluation response.

Vault only includes the entry criteria evaluation in the response when executing the cancel and resumeworkflow workflow actions.

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
Section link for Replace Workflow Owner: replaceworkflowowner
NameDescription
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
Section link for Email Workflow Participants: emailparticipants
NameDescription
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.
NameDescription
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
Section link for Remove Documents from Envelope: removecontent
NameDescription
contents__sys
required
The id of the document to remove from the workflow. To remove multiple documents, use a comma-separated list of ids.
Update Workflow Due Date: updateworkflowduedate
Section link for 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.

NameDescription
workflow_due_date
required
The new due date for the workflow, in the format YYYY-MM-DD.
Replace Participants: replaceparticipants
Section link for Replace Participants: replaceparticipants

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

Remove Participants: removeparticipants
Section link for Remove Participants: removeparticipants

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

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

Request: Entry Criteria Evaluation

Section link for Request: Entry Criteria Evaluation
curl -X POST -H "Authorization: {AUTH_VALUE}" \
-H "Content-Type: application/x-www-form-urlencoded" \
https://myvault.veevavault.com/api/v26.3/objects/objectworkflows/801/actions/cancel?entrycriteria=true

Response: Entry Criteria Evaluation

Section link for Response: Entry Criteria Evaluation
{
  "responseStatus": "FAILURE",
  "errors": [
    {
      "type": "OPERATION_NOT_ALLOWED",
      "message": "Record cannot be updated: Entry criteria requirement for state [in_review_state__c] failed : Payment Terms required before approving this contract"
    }
  ],
  "source_context": {
    "is_nested": false,
    "type": "document",
    "document_id": 100,
    "minor_version_number__v": 0,
    "major_version_number__v": 1,
    "lifecycle": "contract_management_lifecycle__c",
    "target_state": "in_review_state__c"
  },
  "entry_criteria": [
    {
      "type": "field",
      "message": "Payment Terms required before approving this contract.",
      "field": {
        "name": "payment_terms__c",
        "url": "/api/v26.3/metadata/objects/documents/properties"
      }
    },
    {
      "type": "message",
      "message": "Formula must be TRUE."
    }
  ]
}

If the {workflow_action} executes successfully, the response returns SUCCESS. For example, the cancel workflow action.

If a request to cancel or resume a workflow results in FAILURE due to unmet entry criteria and entrycriteria=true, the response includes a structured evaluation of entry criteria violations for the affected records. Learn more about the entry criteria evaluation response.

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.