> 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/envelope-fields.md).
# Envelope fields
This document explains how to configure template fields and send valid field values in DocStudio envelopes.
### Configure fields and send values
{% columns %}
{% column %}
#### Configure in the template
Set the field type, name, role, validation, options, and placement.
{% endcolumn %}
{% column %}
#### Send in the envelope
Reuse the document ID and field name. Send only the field value.
{% endcolumn %}
{% endcolumns %}
Fields are configured in the template. The template defines the field type, field name, role, validation rules, placeholder, search behavior, and other settings.
Example template field:
```xml
```
When you send or fill an envelope, you do not recreate the full field configuration. You reuse the field name from the template and pass the field value.
Example envelope field value:
```xml
ACME Ltd
```
{% hint style="warning" %}
Use the document ID and field name from the same template version. Do not recreate template field configuration in an envelope request.
{% endhint %}
### Field names
Field names connect envelope values with template fields. When you pass a value in an envelope request, DocStudio uses the field name to find the matching field in the selected document.
Example:
```xml
ACME Ltd
```
Use the exact field name from the template structure. Do not rename fields in the envelope request, even if the new name looks clearer. Field names must match the template field names and should stay unique within one document.
Use field names with 1 to 128 characters. Do not use `&`, `"`, `<`, or `>`.
### Role assignment
Most fields are assigned to a recipient role with `roleId`. The role defines which participant can fill, select, upload, or sign that field.
Example:
```xml
```
The `roleId` comes from the template flow. When you send the envelope, the same role is assigned to a real recipient mailbox in the envelope flow.
Example:
```xml
```
If a field is assigned to one role, another role should not try to fill it unless the workflow allows that action. When a fill request fails, check whether the current mailbox is assigned to the active role that owns the field.
### Common field attributes
Field attributes define field behavior in the template and envelope. Exact attributes depend on the field type.
{% columns %}
{% column %}
* `type` — field type
* `name` — field name used in envelope requests
* `roleId` — recipient role that fills the field
* `placeholder` — text shown in the template and envelope
* `optional` — whether a recipient can leave the field empty
* `search` — whether the field value is searchable
{% endcolumn %}
{% column %}
* `min` and `max` — validation limits
* `precision` — supported number precision
* `dictionaryUuid` — source dictionary
* `columnUuid` — dictionary or lookup column
* `attachmentUuid` — uploaded file identifier in envelope values
{% endcolumn %}
{% endcolumns %}
Use only attributes supported by the selected field type.
### XML schemas
Use the **Template XSD** to check the supported field types and configuration attributes used in template XML. It defines field types, role assignments, validation settings, generated fields, PDF placement attributes, and other template configuration.
Use the **Envelope XSD** to validate the XML sent when an envelope is created or filled. Envelope XML reuses the document IDs and field names from the template and provides the values that must be applied to them.
**Download**:
{% file src="/files/z0bsTne1H8PQBnqabHG7" %}
{% file src="/files/xcomGoNpuIpbN4DBaKLM" %}
### Field types
Use field types that match the required value or template behavior:
{% columns %}
{% column %}
* text
* number
* currency
* date
* dropdown
* number-to-text
{% endcolumn %}
{% column %}
* choice
* checkbox
* file
* dictionary
* lookup
* initials
{% endcolumn %}
{% column %}
* dynamic table
* duplicate
* formula
* autonumber
* signature
{% endcolumn %}
{% endcolumns %}
Some fields accept values. Others generate or derive values from template configuration.
### Simple input fields
Simple input fields collect values such as text, numbers, currency amounts, and dates.
Use text fields for plain text. Configure single-line or multiline input and character limits.
Example envelope value:
```xml
ACME Ltd
```
Use number fields for numeric values. Configure formatting, precision, trailing zeros, and numeric limits.
Example envelope value:
```xml
1250.50
```
Use currency fields for monetary values. Currency fields use precision `2` and trailing zeros.
Example envelope value:
```xml
1250.50
```
Use date fields for date or date-time values. Send dates in a format supported by the field configuration, such as `2019-12-31T23:59:59+02:00` or `2019-12-31T23:59:59Z`.
Example envelope value:
```xml
2026-07-15T10:00:00Z
```
### Selection fields
Selection fields let users choose one or more predefined values.
Dropdown fields define a list of options inside the template. The field can also allow custom values or multiple selected values if configured, but `allowCustomValue` and `multiSelect` must not be used together.
Template example:
```xml
```
Envelope value example:
```xml
Germany
```
Choice fields work as radio button groups. In the template, each option is a separate field with `type="radio"`, the same `name`, and a different `value`.
Template example:
```xml
```
Only one option can be selected in the envelope.
Checkbox fields are used when the recipient must select or confirm a checkbox value.
Template example:
```xml
```
Use the checkbox field reference for the exact accepted value format when sending or filling checkbox values through the API.
### File fields
File fields let a recipient or integration attach a file to a field. API integrations must upload the file first, then use the returned uploaded file identifier in the envelope XML.
Upload response example:
```json
{
"attachmentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"filename": "contract.pdf",
"filesize": 0
}
```
Envelope field value example:
```xml
contract.pdf
```
Use `attachmentId` from the upload response as `attachmentUuid` in the envelope XML. Use the returned filename as the field value. Do not use a local file path, external file URL, or filename as a replacement for `attachmentUuid`.
### Number-to-text fields
A Number to text field displays the value of a Number, Currency, or Formula field as words. It is generated automatically and cannot be filled directly by a recipient or integration.
In template XML, Number to text is represented by the `number-to-text` element rather than a regular `field` element. The required attributes are `name`, `relatedTo`, and `language`; `currency` is optional.
```xml
```
Fill only the source field in the envelope XML. DocStudio generates and updates the Number to text value automatically.
```xml
1000.00
```
### Dictionary fields
Dictionary fields let users select values from a predefined dataset. They are useful when field values must come from controlled business data, such as customers, departments, products, regions, or other reference lists.
Template example:
```xml
```
A dictionary field uses `dictionaryUuid` to reference the source dictionary and `columnUuid` to define which dictionary column is displayed as text. If the template uses dictionary fields, make sure the dictionary and column UUIDs belong to the expected dictionary configuration.
### Lookup fields
Lookup fields show related data from a dictionary field in the same document. They display a value from a selected dictionary column.
Template example:
```xml
```
Use lookup fields to provide related values from a selected dictionary entry.
### Dynamic tables and grouped fields
Dynamic tables use repeated field groups. Use them when an envelope needs a variable number of rows.
Example:
```xml
```
Each `fieldset` represents one repeated group or table row. The `index` identifies the repeated set position. Use the exact field group name and field names from the template structure.
### Generated and calculated fields
Some fields should not be filled manually in envelope requests because DocStudio calculates, copies, or generates their values from template configuration or other fields.
This group can include:
* duplicate fields
* formula fields
* autonumber fields
* lookup fields, when the value is derived from a related dictionary field
Use these fields in the template when the value must be generated or derived automatically. In envelope requests, fill the source fields that control the generated value, not the generated field itself, unless the field reference explicitly says otherwise.
{% hint style="warning" %}
Do not fill duplicate, formula, autonumber, or derived lookup fields manually. Send values only for their source fields.
{% endhint %}
### Signature fields
Signature fields define where and how a recipient signs. In the API field reference, the signature field type is `einksign`.
Signature field values can use Base64 PNG data and have image size limits. Use the signature field reference for the exact value requirements before sending or filling signature data through the API.
Example template field:
```xml
```
Do not treat a signature field as a regular text field. It has its own format and validation rules.
### PDF fields
Uploaded PDF templates can also use dynamic fields. For PDF templates, fields require additional placement attributes so DocStudio knows where to render the field on the PDF page.
PDF field placement can include:
* `x`
* `y`
* `width`
* `height`
* `page`
Example:
```xml
```
Use PDF field attributes only when the field must be placed on an uploaded PDF template. For regular structured templates, field placement is handled by the template structure.
### Initials fields
An Initials field collects a recipient’s initials instead of a full electronic signature. In template XML, use a regular `field` element with `type="initials"` and assign it to the role that must complete the field.
```xml
```
For a field placed on a PDF, use the PDF placement attributes defined in the Template XSD, including `page`, `x`, `y`, `width`, and `height`. The assigned recipient completes the field when processing the envelope.
### Searchable fields
Some fields support the `search` attribute. When `search="true"`, the field value can be available in envelope search.
Example:
```xml
```
Use searchable fields for values that must be found later. Do not make every field searchable.
### Optional and required fields
The `optional` attribute controls whether a recipient can leave a field empty. If a required field does not receive a value, the envelope may not move forward until the active participant fills it.
Example required field:
```xml
```
Example optional field:
```xml
```
Use required fields for mandatory values. Use optional fields for values that may be unavailable.
### Field validation
Field validation is defined in the template and applied when the envelope is sent or filled. Validation can depend on the field type and configuration.
Examples:
{% columns %}
{% column %}
* text fields can validate character count
* number and currency fields can validate numeric range
* date fields can validate allowed date offsets
* dropdown fields can validate allowed options
{% endcolumn %}
{% column %}
* dictionary fields can validate dictionary values
* file fields can validate uploaded attachment references
* signature fields can validate signature format and size
{% endcolumn %}
{% endcolumns %}
If the API request sends a value that does not match the field configuration, DocStudio can reject the request or return a validation error.
### Send field values in envelope XML
When you send an envelope, field values are placed inside the document that contains those fields.
Example:
```xml
ACME Ltd1250.502026-07-15T10:00:00Z
```
The document ID and field names must come from the same template version. Do not mix field values from one template with document IDs from another template.
Use one payload to combine values for different field types:
```xml
ACME Ltd2026-07-15T10:00:00ZACME Ltdcontract.pdf
```
### Validation checklist
If field values are not applied or validation fails, check these points:
{% columns %}
{% column %}
* The field exists in the selected template version.
* The field name matches the template exactly.
* The field is placed under the correct document ID.
* The field belongs to the expected recipient role.
* The current mailbox can fill the field at this workflow step.
* The field value matches the field type.
* Required fields are not empty.
{% endcolumn %}
{% column %}
* Number, currency, date, and text values match validation rules.
* Dropdown or choice values match allowed options.
* Dictionary fields use the correct dictionary and column UUIDs.
* File fields use valid uploaded attachment UUIDs.
* Dynamic table field groups use the correct group name and fieldset indexes.
* PDF fields include placement attributes for uploaded PDF templates.
* Reserved XML characters are escaped correctly.
{% endcolumn %}
{% endcolumns %}
### Related topics
{% columns %}
{% column %}
* [Working with XML payloads](/guides/xml-payloads.md)
* [Working with templates and reusable IDs](/guides/templates-and-reusable-ids.md)
* [Send your first envelope](/introduction/send-your-first-envelope.md)
{% endcolumn %}
{% column %}
* [Fill Envelope](/api-reference/fill-envelope.md)
* [Upload Attachments](/api-reference/upload-attachments.md)
* [Error handling and API error codes](/error-codes/error-handling-and-api-error-codes.md)
{% endcolumn %}
{% endcolumns %}