**Source URL:** https://limited.veevavault.dev/commercial/vault-api/api-reference/20.1/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/20.1/documents/create-documents/create-multiple-documents).

</Aside>
Create a single document.

<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` |
</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. |
| `type__v` | The name of the document type to assign to the new document. |
| `subtype__v` | The name of the document subtype (if one exists on the document type). |
| `classification__v` | The name of the document classification (if one exists on the document subtype). |
| `lifecycle__v` | The name 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. |
| `type__v` | The name of the document type to assign to the new document. |
| `subtype__v` | The name of the document subtype (if applicable). |
| `classification__v` | The name of the document classification (if one exists on the document subtype). |
| `lifecycle__v` | The name 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">
**Optional Parameters in PromoMats**

In PromoMats Vaults, you can also optionally set the following parameters. Learn more about [PromoMats Standard Metrics in Vault Help](https://commercial.veevavault.help/en/lr/58143).

<FieldTable>
| Name | Description |
| --- | --- |
| `global_content_type__v` | The name of the global content type to assign to the new document. If excluded, Vault creates the document with the default global content type, or as “Not Specified” if no default exists. |
| `content_creation_currency__v` | The `id` of the content creation currency type. If excluded, Vault creates the document with the default content creation currency, or as “Not Specified” if no default exists. |
| `content_creation_cost__v` | The `id` of the content creation cost. If excluded, Vault creates the document with the default content creation cost, or as “Not Specified” if no default exists. |
</FieldTable>
</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 name of the document type to assign to the new document. |
| `subtype__v` | The name of the document subtype (if one exists on the document type). |
| `classification__v` | The name of the document classification (if one exists on the document subtype). |
| `lifecycle__v` | The name 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. |
| `type__v` | Set the document type to "Undefined". |
| `lifecycle__v` | Set the document lifecycle to "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.

##### 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 name of the document type to assign to the new CrossLink document. |
| `subtype__v` | The name of the document subtype (if one exists on the document type). |
| `classification__v` | The name of the document classification (if one exists on the document subtype). |
| `lifecycle__v` | The name 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. [Learn more](/vault-api/api-reference/20.1/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. |
| `source_binding_rule__v` | Optional: 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` | Optional: 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` | Optional: 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.



---

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