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

# Replace Participants on Active Workflow

Replace the entire membership of one or more participant groups on a single active workflow with a new, complete set of members. This action is synchronous and returns per-group outcomes immediately. To replace participants across many workflows at once, it is best practice to use [Replace Participants on Multiple Workflows](/regulatory/vault-api/api-reference/26.3/workflows/bulk-active-workflow-actions/replace-participants-on-multiple-workflows).

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 Workflow Task](/regulatory/vault-api/api-reference/26.3/workflows/workflow-tasks/cancel-workflow-task). Initiate a reassign or cancel task with [Initiate Workflow Action](/regulatory/vault-api/api-reference/26.3/workflows/initiate-workflow-action).

<Endpoint path="/api/{version}/objects/objectworkflows/{workflow_id}/actions/replaceparticipants" method="POST" />

## Headers

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

## URI Path Parameters

<FieldTable>
| Name | Description |
| --- | --- |
| `{workflow_id}` | The ID of the active workflow instance. |
</FieldTable>

## Body Parameters

<FieldTable>
| Name | Description |
| --- | --- |
| `participant_groups`<Requiredness type="required" /> | An array of one or more participant-group replacement requests to apply to this workflow. Each item targets one participant group. Order does not matter, and at least one item is required. |
| `participant_groups.participant_group_name`<Requiredness type="required" /> | The name of the participant group to update, for example `approvers__c`. Must exist on the workflow and cannot be repeated within the request. |
| `participant_groups.user_ids`<Requiredness type="conditional" /> | The Vault user IDs that make up the new, complete membership for this group. Required if `group_ids` is omitted or empty. |
| `participant_groups.group_ids`<Requiredness type="conditional" /> | The Vault user group IDs that make up the new, complete membership for this group. 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/objects/objectworkflows/2903/actions/replaceparticipants \
  --data '{
    "participant_groups": [
      { "participant_group_name": "approvers__c", "user_ids": [1024, 1090] }
    ]
  }'
```
</CodeExample>

## Response

<CodeExample title="">
```json
{
  "responseStatus": "SUCCESS",
  "data": [
    {
      "participant_group_name": "approvers__c",
      "responseStatus": "SUCCESS",
      "added":   { "user_ids": [1090], "group_ids": [] },
      "removed": { "user_ids": [2055], "group_ids": [] }
    }
  ]
}
```
</CodeExample>

## Response Details

On `SUCCESS`, the response includes a list of `added` and `removed` user and group IDs, reflecting the actual membership change. If your new set is identical to the current membership, Vault applies no change and returns `NO_DATA_CHANGES` for that group.

---

**Previous:** [Manage Multi-item Workflow Content](/regulatory/vault-api/api-reference/26.3/workflows/workflow-tasks/manage-multi-item-workflow-content)  
**Next:** [Complete Job Step](/regulatory/vault-api/api-reference/26.3/workflows/complete-job-step)