Skip to content

Initiate Object Action on a Single Record

Use this request to initiate an action on a specific object record.

POST/api/{version}/vobjects/{object_name}/{object_record_id}/actions/{action_name}
NameDescription
Content-Typeapplication/x-www-form-urlencoded
Acceptapplication/json (default) or application/xml
NameDescription
object_nameThe object name__v field value.
object_record_idThe object record id field value from which to retrieve user actions.
action_nameThe name of the Objectaction or Objectlifecyclestateuseraction to initiate. You can retrieve this from the Retrieve User Actions request. The format for action_name is Objectaction.{vobject}.{action} or Objectlifecyclestateuseraction.{vobject}.{state}.{action}. For example, Objectlifecyclestateuseraction.country__v.active_state__c.start_wf_useraction__c.
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.

Include any parameters required to initiate the action as name-value pairs in the request body. You can retrieve the required parameters for your action by Retrieving Object User Action Details.

NameDescription
{participant_group_name}.assignment_type__c
conditional
The participant group assignment type for a workflow task, either assigned or available. Required if the workflow initiator must select either Assigned to every user or Available to any user when assigning participants to a task in the workflow start step. For example, part_reviewers__c.assignment_type__c=assigned.
storyEventKey
optional
The ID of the target Story Event object record when executing the Apply Milestone Template action. This is only applicable in Clinical Operations Vaults.

When providing values for field prompts on a start step, task step, or verdict, required fields cannot be omitted, set as blank, or defaulted to their existing value.

To preserve the existing value of a required field prompt, submit the existing value as the new value.

curl -X POST -H "Authorization: {AUTH_VALUE}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d 'due_date__c=2020-03-01T08:00:00.000Z' \
-d 'product__v.generic_name__c=nitroprinaline oxalate' \
-d 'product__v.internal_name__c=Nyaxa' \
-d 'product__v.compound_id__c=CC-127' \
-d 'approvers__c=user:10001399' \
https://myvault.veevavault.com/api/v26.3/vobjects/product__v/00P000000000301/actions/Objectlifecyclestateuseraction.product__v.active_state__c.start_workflow_useraction__c
{
    "responseStatus": "SUCCESS"
}

Request: Entry Criteria Evaluation

Section link for Request: Entry Criteria Evaluation
curl -X POST -H "Authorization: {AUTH_VALUE}" \
https://myvault.veevavault.com/api/v26.3/vobjects/contract__c/VHY2112/actions/Objectlifecyclestateuseraction.contract__c.active_state__c.change_state_to_in_review_useraction1__c?entrycriteria=true

Response: Entry Criteria Evaluation

Section link for Response: Entry Criteria Evaluation
{
  "responseStatus": "FAILURE",
  "errors": [
    {
      "type": "OPERATION_NOT_ALLOWED",
      "message": "Entry criteria requirement for state [in_review_state__c] failed"
    }
  ],
  "source_context": {
    "is_nested": false,
    "type": "object",
    "object_name": "task__c",
    "record_id": "V99000000001005",
    "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/vobjects/contract__c/fields/payment_terms__c"
      }
    }
  ]
}

On SUCCESS, Vault executes the action on the specified object record.

If the request results in FAILURE due to unmet entry criteria and entrycriteria=true, the response includes a structured evaluation of entry criteria violations for that record. Learn more about the entry criteria evaluation response.