Remove Participants from Active Workflow

Remove specific users or groups from one or more participant groups from a single active workflow. This action is synchronous and returns per-group outcomes immediately. To remove participants across many workflows at once, it is best practice to use Remove Participants from Multiple Workflows.

Removing participants applies only to manually-managed or custom SDK participant groups. If you are unfamiliar with workflow participant groups, learn more in Using Object Workflows and Using Document Workflows.

Removing a participant changes participant-group membership only. It does not cancel or reassign tasks already assigned to (or accepted by) that user, those tasks remain assigned. The user can no longer accept available tasks in the group. To end a user's already accepted, in-progress task, use Cancel Task (canceltasks) or Reassign Task (reassigntasks) with the Initiate Workflow Actions on Multiple Workflows endpoint.

POST/api/{version}/objects/objectworkflows/{workflow_id}/actions/removeparticipants

Headers

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

URI Path Parameters

Name	Description
`{workflow_id}`	The ID of the active workflow instance.

Body Parameters

Name	Description
`participant_groups` required	An array of one or more participant-group removal 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` required	The name of the participant group to update, for example `approvers__c`. Retrieve valid names with Retrieve Workflow Action Details. The group must exist on the workflow, must be manually-managed or custom SDK, and cannot be repeated within the request.
`participant_groups.user_ids` conditional	An array of Vault user IDs to remove from this group. Required if `group_ids` is omitted or empty.
`participant_groups.group_ids` conditional	An array of Vault user group IDs to remove from this group. 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/objects/objectworkflows/7601/actions/removeparticipants \
  --data '{
    "participant_groups": [
      { "participant_group_name": "reviewers__c", "user_ids": [61603] }
    ]
  }'

Response

{
  "responseStatus": "SUCCESS",
  "data": [
    {
      "participant_group_name": "reviewers__c",
      "responseStatus": "SUCCESS",
      "removed": { "user_ids": [61603], "group_ids": [] }
    }
  ]
}

Response Details

On SUCCESS, Vault returns details about each removed user or group.

If one or more specified members were not present in a group, Vault skips them and returns a WARNING status for that group. Skipped members are a no-op, meaning Vault does not update the workflow, create an audit entry, fire SDK triggers, or send notifications.