Replace Participants on Multiple Workflows

Replace members from participant groups across multiple active workflows in a single asynchronous job. Vault starts a job and returns a job_id. Use this ID to retrieve per-workflow results with Retrieve Replace Participants on Multiple Workflows Results. Maximum 500 workflows per request.

For each group, Vault atomically removes the members not in your new set and adds the members that are new. The operation is all-or-nothing per group: if adding a new member fails, that group is left unchanged. Members that appear in both the current membership and your new set are unchanged and are not listed in the response.

Replace applies only to manually-managed or custom SDK participant groups. When a group is configured with role constraints, every member you add must satisfy those constraints, otherwise the group returns a FAILURE. Learn more about Roles Allowed to Participate in Configuring Object Workflows.

Replace updates participant-group membership only, it does not move or reassign in-progress work. A task already assigned to (or accepted by) the replaced-out user stays assigned to that user; it is not cancelled or transferred to the new participant. If the group has active tasks, the newly added participant receives a new task. To hand off an in-progress task to another user, use Reassign Task. Or, once a new task is assigned to your newly added participant, you can cancel the previous already-assigned task with Cancel Task. Initiate a reassign or cancel task with Initiate Workflow Actions on Multiple Workflows.

POST/api/{version}/object/workflow/actions/replaceparticipants

Headers

Name	Description
`Content-Type`	`application/json`
`Accept`	`application/json`

Body Parameters

Name	Description
`items` required	An array of replacement items. Each item must be a unique (`workflow_id`, `participant_group_name`) pair.
`items[].workflow_id` required	The active workflow instance ID for this item.
`items[].participant_group_name` required	The participant group to update on this workflow.
`items[].user_ids` conditional	Vault user IDs to replace. Required if `group_ids` is omitted or empty.
`items[].group_ids` conditional	Vault user group IDs to replace. Required if `user_ids` is omitted or empty.

Request

curl -X POST -H "Authorization: {AUTH_VALUE}" \
  -H "Content-Type: application/json" \
https://myvault.veevavault.com/api/v26.3/object/workflow/actions/replaceparticipants \
  --data '{
    "items": [
      { "workflow_id": 2903, "participant_group_name": "approvers__c", "user_ids": [1024, 1090] },
      { "workflow_id": 2904, "participant_group_name": "reviewers__c", "group_ids": [710] }
    ]
  }'

Response

{
  "responseStatus": "SUCCESS",
  "data": {
    "job_id": 93602,
    "url": "/api/v26.3/services/jobs/93602",
    "results_url": "/api/v26.3/object/workflow/actions/replaceparticipants/results/93602"
  }
}

Response Details

On SUCCESS, Vault returns a job_id. You can poll the job status with Retrieve Job Status, and once complete, obtain results from Retrieve Replace Participants on Multiple Workflows Results.