> 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/api-reference/upload-attachments.md).

# Upload Attachments

This document contains details for the /api/v1/envelope/attachment endpoint, including headers, request body, response fields, and status codes.

### Endpoint

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

### Headers

<table><thead><tr><th width="192">Header</th><th width="211">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><code>multipart/form-data</code></td></tr><tr><td><code>Mailbox</code></td><td>No</td><td>UUID of the current mailbox context</td></tr></tbody></table>

### Query parameters

<table><thead><tr><th width="115">Parameter</th><th width="86">Type</th><th width="106">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>type</code></td><td>string</td><td>No</td><td>File category: <code>all</code>, <code>document</code>, <code>file</code>, <code>image</code>, or <code>archive</code></td></tr></tbody></table>

### Request

Send the file as `multipart/form-data` in the required `file` field.

<table><thead><tr><th width="91">Field</th><th width="101">Type</th><th width="220">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>file</code></td><td>binary</td><td>Yes</td><td>File to upload</td></tr></tbody></table>

### Request example

```bash
curl --request POST \
  "https://{baseUrl}/api/v1/envelope/attachment?type=document" \
  --header "Authorization: Bearer {token}" \
  --header "Mailbox: {mailboxUuid}" \
  --form "file=@contract.pdf"
```

Let the HTTP client generate the multipart boundary automatically.

### Response

The endpoint returns `201 Created` with the uploaded attachment details.

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

<table><thead><tr><th width="153">Field</th><th width="187">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>filename</code></td><td>string</td><td>Name of the uploaded file</td></tr><tr><td><code>attachmentId</code></td><td>UUID</td><td>Identifier of the uploaded attachment</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>MIME type of the uploaded file</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>

### Attachment references

Set `attachmentUuid` to the returned `attachmentId`.

#### External document

Use the attachment as an external envelope document:

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

#### File field

Use the attachment as a file field value:

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

### Status codes

<table><thead><tr><th width="324">Code</th><th>Description</th></tr></thead><tbody><tr><td><code>201</code></td><td>Attachment uploaded successfully</td></tr><tr><td><code>400</code></td><td>Invalid request body, query parameter, or headers</td></tr><tr><td><code>401</code></td><td>Missing, invalid, or expired authorization token</td></tr><tr><td><code>403</code></td><td>No access to the specified mailbox</td></tr><tr><td><code>413</code></td><td>Uploaded file exceeds the allowed size</td></tr></tbody></table>

### Related topics

* [XML payloads](/guides/xml-payloads.md)
* [Templates and reusable IDs](/guides/templates-and-reusable-ids.md)
* [Envelope fields](/guides/envelope-fields.md)
* [Send your first envelope](/introduction/send-your-first-envelope.md)
* [Send Envelope](/api-reference/send-envelope.md)
* [Fill Envelope](/api-reference/fill-envelope.md)