**Source URL:** https://limited.veevavault.dev/qualityone/vault-api/api-reference/26.3/workflows/bulk-active-workflow-actions/replace-participants-on-multiple-workflows

# 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](/qualityone/vault-api/api-reference/26.3/workflows/bulk-active-workflow-actions/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](https://platform.veevavault.help/en/lr/33550).

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](/qualityone/vault-api/api-reference/26.3/workflows/bulk-active-workflow-actions/initiate-workflow-actions-on-multiple-workflows).

<Endpoint path="/api/{version}/object/workflow/actions/replaceparticipants" method="POST" />

## Headers

<FieldTable>
| Name | Description |
| --- | --- |
| `Content-Type` | `application/json` |
| `Accept` | `application/json` |
</FieldTable>

## Body Parameters

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

## Request

<CodeExample title="">
```bash
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] }
    ]
  }'
```
</CodeExample>

## Response

<CodeExample title="">
```json
{
  "responseStatus": "SUCCESS",
  "data": {
    "job_id": 93602,
    "url": "/api/v26.3/services/jobs/93602",
    "results_url": "/api/v26.3/object/workflow/actions/replaceparticipants/results/93602"
  }
}
```
</CodeExample>

## Response Details

On `SUCCESS`, Vault returns a `job_id`. You can poll the job status with [Retrieve Job Status](/qualityone/vault-api/api-reference/26.3/jobs/retrieve-job-status), and once complete, obtain results from [Retrieve Replace Participants on Multiple Workflows Results](/qualityone/vault-api/api-reference/26.3/workflows/bulk-active-workflow-actions/retrieve-replace-participants-on-multiple-workflows-results).

---

**Previous:** [Remove Participants from Multiple Workflows](/qualityone/vault-api/api-reference/26.3/workflows/bulk-active-workflow-actions/remove-participants-from-multiple-workflows)  
**Next:** [Remove Participant from All Active Workflows](/qualityone/vault-api/api-reference/26.3/workflows/bulk-active-workflow-actions/remove-participant-from-all-active-workflows)