**Source URL:** https://limited.veevavault.dev/clinical/vault-api/api-reference/23.3/object-lifecycle-workflows/multi-record-workflows/initiate-multi-record-workflow.md

# Initiate Multi-Record Workflow



Initiate a multi-record workflow on a set of records. If any record is not in the relevant state or does not meet configured field conditions, the API returns `INVALID_DATA` for the invalid records and the workflow does not start.

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

## Headers {#headers}

<FieldTable>
| Name | Description |
| --- | --- |
| `Content-Type` | `application/x-www-form-urlencoded` |
| `Accept` | `application/json` (default) or `application/xml` |
</FieldTable>

## URI Path Parameters {#uri-path-parameters}

<FieldTable>
| Name | Description |
| --- | --- |
| `{workflow_name}` | The workflow `name` value. |
</FieldTable>

## Body Parameters {#body-parameters}

The following parameters are required, but an Admin may set other fields as required in your Vault. To find which fields are required to start this workflow, [Retrieve Multi-Record Workflow Details](/vault-api/api-reference/23.3/object-lifecycle-workflows/multi-record-workflows/retrieve-multi-record-workflow-details).

<FieldTable>
| Name | Description |
| --- | --- |
| `contents__sys` | Input a comma-separated list of records, in the format `Object:{objectname}.{record_ID}`. For example, `Object:product__c.V3O000000005001`. Maximum 100 records. |
| `description__sys` | Description of the workflow. Maximum 128 characters. |
</FieldTable>

##### Add Participants {#add-participants}

To add participants to a workflow, add the name of the participant control to the body of the request. The value should be a comma-separated list of user and group IDs in the format `{user_or_group}:{id}`. For example, `approvers__c: user:123,group:234`. Use [Retrieve Document Workflow Details](/vault-api/api-reference/23.3/document-lifecycle-workflows/document-workflows/retrieve-document-workflow-details) to get the names of all participant controls for the workflow.

##### Values in Required Field Prompts {#values-in-required-field-prompts}

Required fields cannot be omitted, set as blank, or defaulted to their existing value.

To preserve the existing value of a required field prompt in a workflow on a single record, submit the existing value as the new value.

For a workflow on multiple records, there is no way to preserve existing values in a field if that field is a required prompt. Setting a value for a prompt updates all records to the same single value.

## Request {#request}

<CodeExample title="">
```
curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "contents__sys: Object:feature_record__c.V3O000000005001,Object:feature_record__c.V3O000000005002" \
-d "description__sys: CSR Approval" \
-d "exec_approver__c: user:10081" \
https://myvault.veevavault.com/api/v22.3/objects/objectworkflows/actions/Objectworkflow.approval__c

```
</CodeExample>

## Response {#response}

<CodeExample title="">
```
{
   "responseStatus": "SUCCESS",
   "data": {
       "record_url": "/api/v22.3/vobjects/envelope__sys/0ER000000009003",
       "record_id__v": "0ER000000009003",
       "workflow_id": "8703"
   }
}

```
</CodeExample>

## Response Details {#response-details}

On SUCCESS, the response includes the following:

<FieldTable>
| Name | Description |
| --- | --- |
| `record_id__v` | The `id` value of the `envelope__sys` record. |
| `workflow_id` | The workflow `id` field value. |
</FieldTable>

## Manage Multi-record Workflow Tasks {#manage-multi-record-workflow-tasks}

Multi-record workflows are configured on the `envelope__sys` object. You can use the [Workflow Task](/vault-api/api-reference/23.3/workflows/workflow-tasks) endpoints to retrieve workflow tasks, details, and initiate tasks.

## Remove Records from Workflow {#remove-records-from-workflow}

You can remove one or more records from an `envelope__sys` object using the `removecontent` action in the [Initiate Workflow Action](/vault-api/api-reference/23.3/workflows/initiate-workflow-action) endpoint.



---

**Previous:** [Retrieve Multi-Record Workflow Details](/clinical/vault-api/api-reference/23.3/object-lifecycle-workflows/multi-record-workflows/retrieve-multi-record-workflow-details)  
**Next:** [Users](/clinical/vault-api/api-reference/23.3/users)