> 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/template-api/template-dynamic-fields-api/file-field-api.md).

# File Field API

Use this page to add a file field to template XML. Assign the field to a role with `roleId`, then upload the actual file later and pass the returned attachment ID in the envelope request.

### File field example

```xml
<field
    type="attachment"
    name="supporting_file"
    roleId="fd8cb669-db1d-41e1-8f6c-2ad3f8fa981a"
    placeholder="Upload file"
    optional="false"
    attachmentType="all"
/>
```

### Required attributes

* `type` — field type. Use `attachment`.
* `name` — field name. Use 1 to 128 characters. Do not use `&`, `"`, `<`, or `>`. Keep the value unique within one document.
* `roleId` — role identifier for the recipient who uploads the file.
* `attachmentType` — allowed upload type. Use one of these values: `all`, `file`, `document`, `image`, `archive`.

### Optional attributes

* `placeholder` — placeholder text shown in the template and envelope. Use 0 to 1024 characters. If you omit it, the envelope shows the field name.
* `optional` — set to `true` if the recipient can leave the field empty. If you omit it, the default value is `false`.

### Supported attachment types

* `all` — `.pdf`, `.doc`, `.docx`, `.xls`, `.xlsx`, `.xlsm`, `.xlsb`, `.xml`, `.dbf`, `.txt`, `.rtf`, `.csv`, `.xps`, `.eml`, `.msg`, `.emlx`, `.rpmsg`, `.crt`, `.pem`, `.der`, `.cer`, `.ppt`, `.pptx`, `.png`, `.jpg`, `.jpeg`, `.tiff`, `.tif`, `.zip`, `.7z`, `.rar`, `.asice`
* `file` — `.pdf`, `.doc`, `.docx`, `.xls`, `.xlsx`, `.xlsm`, `.xlsb`, `.xml`, `.dbf`, `.txt`, `.rtf`, `.csv`, `.xps`, `.eml`, `.msg`, `.emlx`, `.rpmsg`, `.crt`, `.pem`, `.der`, `.cer`, `.ppt`, `.pptx`
* `document` — `.pdf`
* `image` — `.png`, `.jpg`, `.jpeg`, `.tiff`, `.tif`
* `archive` — `.zip`, `.7z`, `.rar`, `.asice`

### How it works

1. Add the file field to the template.
2. Upload the file with [Upload Attachment/External Documents Method](/api-documentation/api-methods/upload-attachment-external-documents-method.md).
3. Pass the uploaded attachment ID in the envelope request.

### Related topics

* [Template Dynamic Fields API](/api-documentation/template-api/template-dynamic-fields-api.md)
* [Template Structure API](/api-documentation/template-api/template-structure-api.md)
* [Upload Attachment/External Documents Method](/api-documentation/api-methods/upload-attachment-external-documents-method.md)
* [Send Envelope](/api-documentation/envelope/send-envelope.md)