> 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-documentation/api-methods/upload-attachment-external-documents-method.md).

# Upload Attachment/External Documents Method

### Method

<table><thead><tr><th width="321">Method</th><th>POST</th></tr></thead><tbody><tr><td>URL</td><td><code>/api/v1/envelope/attachment</code></td></tr><tr><td>Authorization</td><td>Bearer {token}</td></tr><tr><td>Content-Type</td><td>application/json</td></tr><tr><td>Mailbox UUID header</td><td><code>{uuid}</code></td></tr><tr><td>Body</td><td><code>binary file contents</code></td></tr></tbody></table>

Use this endpoint to upload a file before you send or fill an envelope. The response returns the uploaded file identifier and filename.

### How it works

Upload the file first. Then use the returned `attachmentId` in the next envelope request.

Use this flow for file fields and external documents. Keep the same mailbox context for the upload and the next envelope request.

### Request body

Send the raw file body in binary format. Do not wrap the file in JSON.

### Request example

```
<binary file body>
```

### Response example

```json
{
  "attachmentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "filename": "contract.pdf",
  "filesize": 0
}
```

### How to use the uploaded file

Use `attachmentId` as the `attachmentUuid` value in the envelope XML. Use `filename` as the field value.

```xml
<document id="16c545db-1002-4efb-a4de-b46bc5ed4885">
    <field name="File" attachmentUuid="3fa85f64-5717-4562-b3fc-2c963f66afa6">contract.pdf</field>
</document>
```

Use the same uploaded file in an external document flow when the template expects an attachment-based document.

### Related topics

* [Envelope Structure](https://support.docstudio.com/docstudio-docs/docstudio-for-developers/api-documentation/envelope/envelope-structure)
* [Send Envelope](https://support.docstudio.com/docstudio-docs/docstudio-for-developers/api-documentation/envelope/send-envelope)
* [File Field API](https://support.docstudio.com/docstudio-docs/docstudio-for-developers/template-api/template-dynamic-fields-api/file-field-api)