Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

XML payloads

This document explains how to build, escape, and validate XML payloads for DocStudio API requests.

Some DocStudio API endpoints use XML payloads to describe templates, envelopes, documents, recipient roles, and field values.

When XML payloads are used

DocStudio uses XML payloads when a request needs to describe a document or an envelope structure. XML is used because templates and envelopes can contain:

  • documents

  • fields

  • roles

  • field groups

  • dynamic tables

  • attachments

  • workflow settings

Common API operations that can use XML payloads include:

  • creating a template

  • creating and sending an envelope from a template

  • filling fields in an existing envelope

  • passing document field values

  • assigning recipient mailboxes to template roles

  • referencing uploaded files in file fields

  • working with dynamic tables and field groups

Not every API endpoint uses XML. Many endpoints use JSON, query parameters, path parameters, or file upload formats.

Always check the API reference for the exact request format required by the endpoint.

Send XML in the JSON data field

Use the readable XML form while preparing the payload. Send the same XML as a JSON string in the data field.

Main parts of an envelope XML payload

A basic envelope XML payload usually contains:

  • envelope attributes

  • envelope information

  • workflow roles

  • documents

  • field values

Example:

Envelope attributes

The root envelope element connects the new envelope to a specific template and template version.

Use values from the template structure:

  • templateUuid identifies the template.

  • templateVersion identifies the exact template version.

Use templateUuid, templateVersion, role IDs, document IDs, and field names from the same template version. Do not create or mix these values manually.

Envelope information

The info block contains general envelope information, such as the subject and message.

Use this block to define what recipients see when they receive or open the envelope. The exact available properties depend on the endpoint and envelope settings.

Workflow roles

The flow block assigns real recipient mailboxes to roles from the template.

The id value comes from the template role. The mailboxUuid value identifies the mailbox assigned to that role in the envelope.

The role defines what the participant must do, and the mailbox UUID defines who receives or processes that role.

If the role ID is copied from the wrong template or the mailbox UUID does not belong to an accessible mailbox, the request can fail or the envelope can be sent to the wrong participant.

Documents

The documents block contains the documents included in the envelope and the field values that must be applied to those documents.

  • The documentId must match the document ID from the template structure.

  • Field names must match the field names from that document.

Use the exact field names from the template. A different XML field name may prevent the value from being applied or cause a validation error.

Field values

Field values are passed inside field elements.

Different field types can require different value formats:

  • Text fields use plain text

  • Date fields use a supported date format

  • File fields reference an uploaded attachment

File field example:

Do not use a local file path or file name as the attachment identifier, the attachmentUuid value must come from a previous file upload response.

Dynamic tables and field groups

Dynamic tables and grouped fields use nested field group structures.

Use field groups when the template contains repeatable table rows or grouped field sets.

Example:

Each fieldset is one repeated row. Its index sets the row position.

Use field group and field names exactly as they appear in the template. Do not add names to the envelope request.

Escape XML and JSON values

If a field value contains reserved characters, they must be escaped so the XML remains valid.

Use these XML escapes:

  • & for &

  • &lt; for <

  • &gt; for >

  • &quot; for "

  • &apos; for '

Example:

If reserved characters are not escaped, the API may reject the request because the XML is not valid.

Escape JSON values

When XML is sent inside a JSON string, JSON escaping rules also apply. This means quotation marks inside XML attributes must be escaped.

Readable XML:

XML inside JSON:

If you build requests in code, use a reliable XML builder and JSON serializer when possible. Avoid manually concatenating large XML strings if the integration can generate XML and serialize JSON safely.

Do not send system-generated values

Some values are generated by DocStudio and should not be sent manually in XML payloads.

For example, DocStudio generates the following values:

  • envelope status

  • creation date

  • completion data

  • active role state

  • other system-managed values

The platform controls these values.

Send only the values that the endpoint expects and that your integration needs to provide. Do not copy system-generated values from an existing envelope and try to reuse them in a new request.

Get required values

Before building an envelope XML payload, collect the reusable identifiers from the correct sources.

Use the template structure to get:

  • template UUID

  • template version

  • role IDs

  • document IDs

  • field names

  • field group names

  • field types

  • validation settings

Use mailbox endpoints or existing account data to get:

  • sender mailbox UUID

  • recipient mailbox UUIDs

  • mailbox context required by the endpoint

Use file upload endpoints to get:

  • attachment UUIDs

  • uploaded file metadata

Use the send envelope response to get:

  • envelope UUID

The envelope UUID is returned after the envelope is created or sent.

Save it because you will need it to check status, download documents, or get audit trail data.

Common mistakes

Most XML payload issues happen when the request contains incorrect identifiers, invalid XML, or values that do not match the template configuration.

Common mistakes include:

  • using a template UUID from one template and role IDs from another template

  • using an outdated template version

  • creating role IDs, document IDs, or field names manually

  • using a mailbox UUID that the token owner cannot access

  • sending field values for fields that do not exist in the selected document

  • using the wrong field value format

  • forgetting to escape XML reserved characters

  • forgetting to escape quotation marks when XML is placed inside JSON

  • sending XML that is not wrapped in the JSON data field

  • using a file name instead of an attachment UUID for file fields

  • copying system-generated envelope values into a new request

Troubleshooting checklist

If an XML payload fails validation, check these points first:

  • The XML is valid and well-formed.

  • The XML is passed as a string inside the JSON data field.

  • Quotation marks are escaped correctly in the JSON string.

  • Reserved XML characters are escaped in field values.

  • The template UUID and template version are correct.

  • Role IDs and document IDs match the selected template version.

  • Mailbox UUIDs are correct and accessible.

  • Field names match the template exactly.

  • Field values match the expected field types and validation rules.

  • File fields use valid attachment UUIDs.

  • Dynamic table and field group names match the template.

  • The request does not include values that DocStudio generates automatically.

Related topics

PreviousTemplate Structure API
NextEnvelope Structure

Last updated

Was this helpful?