**Source URL:** https://limited.veevavault.dev/regulatory/vault-api/api-reference/24.3/document-lifecycle-workflows/document-workflows/initiate-document-workflow.md

# Initiate Document Workflow



Initiate a document workflow on a set of documents.

<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 document 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 Document Workflow Details](/vault-api/api-reference/24.3/document-lifecycle-workflows/document-workflows/retrieve-document-workflow-details).

<FieldTable>
| Name | Description |
| --- | --- |
| `contents__sys` | Input a comma-separated list of document `id` field values, in the format `Document:{doc_id}`. For example, `Document:101,Document:102,Document:103`. To indicate specific document versions, use the format `DocumentVersion:{doc_version_id}`. For example, `DocumentVersion:115_0_1,DocumentVersion:116_0_2`. Maximum 100 documents. |
| `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/24.3/document-lifecycle-workflows/document-workflows/retrieve-document-workflow-details) to get the names of all participant controls for the workflow.

## Request {#request}

<CodeExample title="">
```
curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/json" \
-d "contents__sys: Document:501,Document:502" \
-d "description__sys: Content Approval" \
https://myvault.veevavault.com/api/v25.2/objects/documents/actions/Objectworkflow.content_document_workflow__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 [501,502] for parameter [contents__sys] specified"
    }
  ]
}

```
</CodeExample>

## Response Details {#response-details}

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.

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

Document workflows share some of the same capabilities as object workflows and are configured on the `envelope__sys` object. You can use the [Workflow Task](/vault-api/api-reference/24.3/workflows/workflow-tasks) endpoints to retrieve document workflow tasks, task details, and initiate 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/24.3/workflows/initiate-workflow-action) endpoint.



---

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