> For the complete documentation index, see [llms.txt](https://developers.docstudio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.docstudio.com/guides/files-and-external-documents.md).

# Files and external documents

This document explains how to upload files and use them in DocStudio envelopes.

### Upload attachment

Use this endpoint to upload a new attachment.

| Method | Endpoint                      |
| ------ | ----------------------------- |
| `POST` | `/api/v1/envelope/attachment` |

### Headers

<table><thead><tr><th width="189.4444580078125">Header</th><th width="116.7777099609375">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>Authorization</code></td><td>Yes</td><td>Bearer authorization token</td></tr><tr><td><code>Content-Type</code></td><td>Yes</td><td>Use <code>multipart/form-data</code></td></tr><tr><td><code>Mailbox</code></td><td>No</td><td>Mailbox context header with the current mailbox UUID</td></tr></tbody></table>

### Query parameters

| Parameter | Type   | Required | Description                                                          |
| --------- | ------ | -------- | -------------------------------------------------------------------- |
| `type`    | string | No       | Uploaded file type: `all`, `document`, `file`, `image`, or `archive` |

Use `type` to specify the uploaded file category. Omit the parameter when no category is needed.

| Value      | Description              |
| ---------- | ------------------------ |
| `all`      | All supported file types |
| `document` | Document files           |
| `file`     | Files                    |
| `image`    | Image files              |
| `archive`  | Archive files            |

### Request body

The endpoint accepts `multipart/form-data`. The uploaded file must be passed in the required `file` field.

| Field  | Type   | Required | Description    |
| ------ | ------ | -------- | -------------- |
| `file` | binary | Yes      | File to upload |

```http
POST /api/v1/envelope/attachment?type=document
Authorization: Bearer {token}
Content-Type: multipart/form-data
Mailbox: {mailboxUuid}

file=@contract.pdf
```

### Response

The endpoint returns `201 Created` with information about the uploaded attachment.

```json
{
  "filename": "contract.pdf",
  "attachmentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "filesize": 204800,
  "contentType": "application/pdf",
  "updatedPdf": "string"
}
```

<table><thead><tr><th width="161.2222900390625">Field</th><th width="163">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>filename</code></td><td>string</td><td>Uploaded file name</td></tr><tr><td><code>attachmentId</code></td><td>UUID</td><td>Uploaded attachment ID</td></tr><tr><td><code>filesize</code></td><td>integer</td><td>Uploaded file size in bytes</td></tr><tr><td><code>contentType</code></td><td>string</td><td>Uploaded file content type</td></tr><tr><td><code>updatedPdf</code></td><td>byte string</td><td>Updated PDF data, when included in the response</td></tr></tbody></table>

Save the `attachmentId` value from the response. This value is the uploaded file identifier that must be used later in envelope XML.

### Status codes

| Code | Description                      |
| ---- | -------------------------------- |
| 201  | Attachment uploaded successfully |

### Use the uploaded file in envelope XML

Pass `response.attachmentId` to the `attachmentUuid` attribute in envelope XML.

<table><thead><tr><th width="187.888916015625">Upload response field</th><th width="198.888916015625">Envelope XML attribute</th><th>Description</th></tr></thead><tbody><tr><td><code>attachmentId</code></td><td><code>attachmentUuid</code></td><td>Uploaded file ID returned by the upload endpoint and used as the uploaded file reference in envelope XML</td></tr><tr><td><code>filename</code></td><td>Field value</td><td>Uploaded file name, used as the field value when the template expects a visible file name</td></tr></tbody></table>

#### External document

Use this structure for an external document.

```xml
<document id="{documentId}" attachmentUuid="{attachmentId}" />
```

#### File upload field

Use this structure for a file upload field.

```xml
<document id="{documentId}">
  <field name="File" attachmentUuid="{attachmentId}">contract.pdf</field>
</document>
```

The field name must match the field name in the selected template. The document ID must also belong to the same template version that is used in the envelope request.

{% hint style="warning" %}
Use `multipart/form-data` and include the required `file` field. Pass the returned `attachmentId` to `attachmentUuid`. Do not use a local path, external URL, or generated UUID.
{% endhint %}

### Related topics

{% columns %}
{% column %}

* [Authentication and application tokens](/introduction/authentication-and-application-tokens.md)
* [Working with XML payloads](/guides/xml-payloads.md)
* [Working with templates and reusable IDs](/guides/templates-and-reusable-ids.md)
  {% endcolumn %}

{% column %}

* [Working with envelope fields](/guides/envelope-fields.md)
* [Send your first envelope](/introduction/send-your-first-envelope.md)
* [Send Envelope](/api-reference/send-envelope.md)
  {% endcolumn %}
  {% endcolumns %}