**Source URL:** https://limited.veevavault.dev/clinical/vault-api/api-reference/21.1/multi-document-workflows/initiate-multi-document-workflow.md

# Initiate Multi-Document Workflow



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

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

## Headers {#headers}

<FieldTable>
| Name | Description |
| --- | --- |
| `Content-Type` | `application/json` (default) or `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 multi-document workflow `name` value. |
</FieldTable>

## Body Parameters {#body-parameters}

<FieldTable>
| Name | Description |
| --- | --- |
| `documents__sys` | Input a comma-separated list of document `id` field values. Maximum 100 documents. |
| `participant_name` | Enter the participant name and input the user or group `id` value. For example, `approvers__c: user:123,group:234`. |
| `description__sys` | Description of the workflow. Maximum 128 characters. |
</FieldTable>

## Request {#request}

<CodeExample title="">
```
curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/json" \
-d "approver__c: user:83610" \
-d "exec_approver__c: user:10081" \
-d "documents__sys: 56,31,25" \
-d "description__sys: CSR Approval" \
https://myvault.veevavault.com/api/v18.3/objects/documents/actions/Objectworkflow.clinical_study_report_approval__c

```
</CodeExample>

## Response : Success {#response--success}

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

```
</CodeExample>

## Response : Failure {#response--failure}

<CodeExample title="">
```
{
    "responseStatus": "FAILURE",
    "errors": [
      {
      "type": "INVALID_DATA",
      "message": "Invalid value [94] specified for parameter [documents__sys] : documents are in invalid lifecycles"
    }
  ]
}

```
</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-Document Workflow Tasks {#manage-multi-document-workflow-tasks}

Multi-document workflows share some of the same capabilities as object workflows and are configured on the `envelope_sys` object. You can use the [Object Workflow Tasks](/vault-api/api-reference/21.1/object-lifecycle-workflows/workflow-tasks) endpoints to retrieve multi-document workflow tasks, task details and initiate multi-document workflow tasks.

## Remove Documents from Envelope {#remove-documents-from-envelope}

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



---

**Previous:** [Retrieve Multi-Document Workflow Details](/clinical/vault-api/api-reference/21.1/multi-document-workflows/retrieve-multi-document-workflow-details)  
**Next:** [Object Lifecycle & Workflows](/clinical/vault-api/api-reference/21.1/object-lifecycle-workflows)