Envelope fields
This document explains how to configure template fields and send valid field values in DocStudio envelopes.
Configure fields and send values
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:
<field
type="text"
name="customer_name"
placeholder="Enter customer name"
roleId="fd8cb669-db1d-41e1-8f6c-2ad3f8fa981a"
optional="false"
search="true"
multilines="false"
min="1"
max="128"
/>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:
<field name="customer_name">ACME Ltd</field>Use the document ID and field name from the same template version. Do not recreate template field configuration in an envelope request.
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:
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:
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:
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.
type— field typename— field name used in envelope requestsroleId— recipient role that fills the fieldplaceholder— text shown in the template and envelopeoptional— whether a recipient can leave the field emptysearch— whether the field value is searchable
minandmax— validation limitsprecision— supported number precisiondictionaryUuid— source dictionarycolumnUuid— dictionary or lookup columnattachmentUuid— uploaded file identifier in envelope values
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:
Field types
Use field types that match the required value or template behavior:
text
number
currency
date
dropdown
number-to-text
choice
checkbox
file
dictionary
lookup
initials
dynamic table
duplicate
formula
autonumber
signature
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:
Use number fields for numeric values. Configure formatting, precision, trailing zeros, and numeric limits.
Example envelope value:
Use currency fields for monetary values. Currency fields use precision 2 and trailing zeros.
Example envelope value:
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:
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:
Envelope value example:
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:
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:
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:
Envelope field value example:
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.
Fill only the source field in the envelope XML. DocStudio generates and updates the Number to text value automatically.
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:
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:
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:
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.
Do not fill duplicate, formula, autonumber, or derived lookup fields manually. Send values only for their source fields.
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:
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:
xywidthheightpage
Example:
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.
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:
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:
Example optional field:
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:
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
dictionary fields can validate dictionary values
file fields can validate uploaded attachment references
signature fields can validate signature format and size
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:
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:
Validation checklist
If field values are not applied or validation fails, check these points:
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.
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.
Related topics
Last updated
Was this helpful?