Envelope Structure

This document contains the envelope XML structure, including the fields you can include in the request body.

Looking for user documentation?

If you want to learn how to use DocStudio in the interface, open the user documentation. It explains how to sign in, create and send envelopes, work with templates, sign documents, manage mailboxes, and configure account settings.

Open DocStudio Knowledge Base

Use this XML inside the data field of envelope API requests. Send only the fields your request needs.

The platform generates some envelope properties automatically.

Example

<envelope templateUuid="1997a1b4-88e3-4f58-88ca-fcd2c6fb5869" templateVersion="4a303734-a118-44a2-aedf-67df61612628">
    <info>
        <subject>Sales agreement</subject>
        <message>Please review the attached data.</message>
        <forwarding delegation="true" sharing="true"/>
    </info>
    <flow>
        <roles>
            <role id="74266bb8-91ad-4e35-9d98-5862fc59cf3e" mailboxUuid="8dcde243-a918-444a-ac7d-44ac88554769"/>
            <role id="a09d90c7-46c1-4f59-8d76-e7975dd8fab6" mailboxUuid="8dcde243-a918-444a-ac7d-44ac88554769"/>
        </roles>
    </flow>
    <documents>
        <document id="16c545db-1002-4efb-a4de-b46bc5ed4885">
            <field name="Text">text</field>
            <field name="Number">10</field>
            <field name="Currency">10.20</field>
            <field name="Date">2024-01-11</field>
            <field name="Dictionary" recordUuid="76d0b4a4-114f-45a6-9039-d654c90a2df2">Record name</field>
            <field name="Signature">data:image/png;base64,iVBORw...K5CYII=</field>
            <field name="File" attachmentUuid="dc317260-adf3-4231-8eaa-588759d7b6f7">agreement.pdf</field>
            <field name="Checkbox">1</field>
            <field name="Dropdown">2</field>
            <field name="Dropdown 2">
                <value>1</value>
                <value>2</value>
            </field>
            <field name="1234">Choice</field>
            <fieldgroup name="Table">
                <fieldset index="0">
                    <field name="Text 2">1</field>
                </fieldset>
                <fieldset index="1">
                    <field name="Text 2">2</field>
                </fieldset>
            </fieldgroup>
        </document>
    </documents>
</envelope>

Envelope root

Attribute	Type	Required	Description
templateUuid	UUID	yes	Template ID used to create the envelope
templateVersion	UUID	yes	Template version ID used for validation

Info block

Use <info> to define envelope-level communication settings, including the subject, message, expiration, and forwarding options.

Element or attribute	Type	Required	Description
subject	string	depends	Envelope subject
message	string	no	Short message for recipients
expire	integer	no	Number of days before the envelope expires
forwarding/@delegation	boolean	no	Allow delegation
forwarding/@sharing	boolean	no	Allow sharing

Flow block

Use <flow> to define recipients and map template roles to mailbox IDs.

Element or attribute	Type	Required	Description
role/@id	UUID	yes	Role ID from the template
role/@mailboxUuid	UUID	yes	Mailbox ID assigned to that role

Documents block

Use <documents> to send field values for each template document, including standard fields, dictionary references, file attachments, and table rows.

Element or attribute	Type	Required	Description
document/@id	UUID	yes	Document ID from the template
field/@name	string	yes	Template field name
field value	string	depends	Field value, validated by the template
field/@recordUuid	UUID	depends	Dictionary record ID
field/@attachmentUuid	UUID	depends	Uploaded attachment ID
fieldgroup/@name	string	yes	Dynamic table name
fieldset/@index	integer	yes	Zero-based row index

Dynamic field formats

Text, Number, Currency, Date, and single-select Dropdown

<field name="string">value</field>

• name — field name from the template

• value — field value

The platform validates the value against the template rules.

Multi-select Dropdown

<field name="string">
    <value>1</value>
    <value>2</value>
</field>

Use one <value> element for each selected option.

Dictionary

<field name="string" recordUuid="UUID">value</field>

• name — dictionary field name

• recordUuid — dictionary record ID

• value — record label, if needed

If you send both recordUuid and text, they must match.

Signature

<field name="string">data:image/png;base64,...</field>

Send the signature as a Base64 data URL.

File

<field name="string" attachmentUuid="UUID">filename.ext</field>

Upload the file first, then send the returned attachment ID. Use Upload Attachment/External Documents Method to get attachmentUuid.

Checkbox

<field name="string">1</field>

Send 1 to mark the checkbox as selected. Skip the field when it is optional and unchecked.

Choice

<field name="group-name">option-name</field>

• name — radio group name

• value — selected option name inside that group

Duplicate, Lookup, and Autonumber

Do not send these fields manually. The platform fills them automatically.

Dynamic table

<fieldgroup name="string">
    <fieldset index="0">
        <field name="Text 2">1</field>
    </fieldset>
    <fieldset index="1">
        <field name="Text 2">2</field>
    </fieldset>
</fieldgroup>

Add one <fieldset> for each row you need. Use a zero-based index for each row.

Platform-generated fields

You may also encounter envelope properties generated by the platform.

• created

• status

• date

• roleId

• active

• completed

Treat these fields as system data unless an endpoint requires them.

Related topics

• Envelope Forms

• Fill Envelope

• Dictionary Field API

• File Field API

• Signature Field API