**Source URL:** https://limited.veevavault.dev/regulatory/vault-api/api-reference/23.3/documents/create-documents/create-single-document.md

# Create Single Document



<Aside>If you need to create more than one document, it is best practice to use the [bulk API](/vault-api/api-reference/23.3/documents/create-documents/create-multiple-documents).</Aside>
Create a single document.

The API supports all security settings.

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

## Headers {#headers}

<FieldTable>
| Name | Description |
| --- | --- |
| `Content-Type` | `multipart/form-data` |
| `Accept` | `application/json` (default) or `application/xml` |
| `X-VaultAPI-MigrationMode` | When set to `true`, Vault applies Document Migration Mode limitations to documents created with the request. You must have the *Document Migration* permission to use this header. When used with the `status__v` parameter, allows you to create documents in a state other than Starting State. Learn more about [Document Migration Mode in Vault Help](https://platform.veevavault.help/en/lr/54028). |
</FieldTable>

## Body Parameters {#body-parameters}

There are multiple ways to create a document.

##### Create Document from Uploaded File {#create-document-from-uploaded-file}

Most documents in your Vault are created from uploaded source files, such as a file from your computer. Learn about [Supported File Formats](https://platform.veevavault.help/en/lr/25210) in Vault Help. Once uploaded with values assigned to document fields, Vault generates the viewable rendition, e.g., "mydocument.docx.pdf". Learn about [Viewable Renditions](https://platform.veevavault.help/en/lr/3815) in Vault Help.

<FieldTable>
| Name | Description |
| --- | --- |
| `file` | The filepath of the source document. The maximum allowed file size is 4GB. Only required when creating a document from an uploaded file. If omitted, creates a placeholder. |
| `name__v` | The name of the new document. |
| `type__v` | The label of the document type to assign to the new document. |
| `subtype__v` | The label of the document subtype (if one exists on the document type). |
| `classification__v` | The label of the document classification (if one exists on the document subtype). |
| `lifecycle__v` | The label of the document lifecycle to assign to the new document. |
| `major_version_number__v` | The major version number to assign to the new document. |
| `minor_version_number__v` | The minor version number to assign to the new document. |
</FieldTable>

##### Create Document from Template {#create-document-from-template}

When you create the new document, Vault copies the template file and uses that copy as the source file for the new document. This process bypasses the content upload process and allows for more consistent document creation. Document templates are associated with a specific document type, like documents themselves. Learn about [Document Templates](https://platform.veevavault.help/en/lr/5509) in Vault Help.

<FieldTable>
| Name | Description |
| --- | --- |
| `fromTemplate` | The name of the template to apply. Only required when creating a document from a template. |
| `name__v` | The name of the new document. |
| `type__v` | The label of the document type to assign to the new document. |
| `subtype__v` | The label of the document subtype (if applicable). |
| `classification__v` | The label of the document classification (if one exists on the document subtype). |
| `lifecycle__v` | The label of the document lifecycle to assign to the new document. |
| `major_version_number__v` | The major version number to assign to the new document. |
| `minor_version_number__v` | The minor version number to assign to the new document. |
</FieldTable>
<SiteConditional sites="commercial" id="promomats-document-parameters"></SiteConditional>

##### Create Content Placeholder Document {#create-content-placeholder-document}

Creating a content placeholder document is just like creating a document from an uploaded file, but the `file` parameter is not included in the request. Learn about [Content Placeholders](https://platform.veevavault.help/en/lr/15087) in Vault Help. Admin may set other standard or custom document fields to required in your Vault.

<FieldTable>
| Name | Description |
| --- | --- |
| `name__v` | The name of the new document. |
| `type__v` | The label of the document type to assign to the new document. |
| `subtype__v` | The label of the document subtype (if one exists on the document type). |
| `classification__v` | The label of the document classification (if one exists on the document subtype). |
| `lifecycle__v` | The label of the document lifecycle to assign to the new document. |
| `major_version_number__v` | The major version number to assign to the new document. |
| `minor_version_number__v` | The minor version number to assign to the new document. |
</FieldTable>

##### Create Unclassified Document {#create-unclassified-document}

Unclassified documents are documents which have a source file, but no document type. Learn about [Unclassified Documents](https://platform.veevavault.help/en/lr/15020) in Vault Help.

<FieldTable>
| Name | Description |
| --- | --- |
| `file` | The filepath of the source document. The maximum allowed file size is 4GB. Only required when creating a document from an uploaded file. |
| `type__v` | Set the document type to `Unclassified` or `Undefined`.* |
| `lifecycle__v` | Set the document lifecycle to `Inbox` or `Unclassified`.* |
</FieldTable>
In eTMF Vaults, you can also (optionally) set the following fields:

* `product__v`

* `study__v`

* `study_country__v`

* `site__v`

Any other fields included in the input will be ignored. The document `name__v` will default to the name of the uploaded file.

* Prior to 21R1.3 (API v21.2), the `Unclassified` document type and `Inbox` lifecycle were known as the `Undefined` document type and `Unclassified` lifecycle. Relabeling the `Undefined` document type and `Unclassified` lifecycle may impact the functionality of custom integrations that use the old labels. Check your integrations before updating this label. We recommend that customers experiencing errors change the labels back to their original values until this issue is resolved.

##### Create CrossLink Document {#create-crosslink-document}

When creating a CrossLink document, you must include all document fields that are required for the specified document type/subtype/classification and no file is uploaded. You must also specify the Vault ID and document ID for the source document which will be bound to the new CrossLink document. Learn about [CrossLinks](https://platform.veevavault.help/en/lr/23143) in Vault Help.

<FieldTable>
| Name | Description |
| --- | --- |
| `name__v` | The name of the new CrossLink document. |
| `type__v` | The label of the document type to assign to the new CrossLink document. |
| `subtype__v` | The label of the document subtype (if one exists on the document type). |
| `classification__v` | The label of the document classification (if one exists on the document subtype). |
| `lifecycle__v` | The label of the document lifecycle to assign to the new CrossLink document. |
| `major_version_number__v` | The major version number to assign to the new CrossLink document |
| `minor_version_number__v` | The minor version number to assign to the new CrossLink document. |
| `source_vault_id__v` | The Vault `id` field value of the Vault containing the source document that will be bound to the new CrossLink document. Only required when creating a CrossLink document. [Learn more](/vault-api/api-reference/23.3/domain-information/retrieve-domain-information). |
| `source_document_id__v` | The document `id` field value of the source document that will be bound to the new CrossLink document. Only required when creating a CrossLink document. |
| `source_binding_rule__v` | Possible values are `Latest version`, `Latest Steady State version`, or `Specific Document version`. These define which version of the source document will be bound to the CrossLink document. If not specified, this defaults to the `Latest Steady State version`. |
| `bound_source_major_version__v` | When the `source_binding_rule__v` is set to `Specific Document version`, you must specify the major version number of the source document to bind to the CrossLink document. |
| `bound_source_minor_version__v` | When the `source_binding_rule__v` is set to `Specific Document version`, you must specify the minor version number of the source document to bind to the CrossLink document. |
</FieldTable>

## Request {#request}

<CodeExample title="">
```
curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: multipart/form-data" \
-F "file=@gludacta-document-01.docx" \
-F "name__v=Gludacta Document" \
-F "type__v=Promotional Piece" \
-F "subtype__v=Advertisement" \
-F "classification__v=Web" \
-F "lifecycle__v=Promotional Piece" \
-F "major_version_number__v=0" \
-F "minor_version_number__v=1" \
-F "product__v=0PR0303" \
-F "external_id__v=GLU-DOC-0773" \
https://myvault.veevavault.com/api/v15.0/objects/documents

```
</CodeExample>

## Response {#response}

<CodeExample title="">
```
{
    "responseStatus": "SUCCESS",
    "responseMessage": "successfully created document",
    "id": 773
}

```
</CodeExample>

## Response Details {#response-details}

On SUCCESS, the document is created and assigned a system-managed document `id` field value. The generated document `id` may not be in sequential order.



---

**Previous:** [Create Documents](/regulatory/vault-api/api-reference/23.3/documents/create-documents)  
**Next:** [Create Multiple Documents](/regulatory/vault-api/api-reference/23.3/documents/create-documents/create-multiple-documents)