Envelope MetaData

This document contains an overview of envelope metadata, including how to add, update, and delete metadata for envelopes and envelope forms.

Metadata is available only to API users and is visible only through the API.

Use metadata to store extra envelope data that is not part of the document content. Add, update, and delete metadata through the API.

Metadata can also be added to envelope forms and will be used in all envelopes created from such forms.

Metadata object example

Use a JSON object with key-value pairs.

{
  "customerId": "C-1024",
  "approved": true,
  "externalReference": null
}

Rules

Each key must be 1 to 32 characters long.
Each value can be 0 to 128 characters long.
Supported value types are string, boolean, and null.

Add or update metadata for an envelope

Use Swagger UI to add new metadata or overwrite existing values with the envelope metadata update endpoint.

Example request body

{
  "customerId": "C-1024",
  "approved": true,
  "externalReference": null
}

How metadata looks for an API user

The API exposes metadata as part of the envelope data.

{
  "uuid": "89499ba2-287d-404c-87b0-342dc5b01b6a",
  "subject": "Sales agreement",
  "metadata": {
    "customerId": "C-1024",
    "approved": true,
    "externalReference": null
  }
}

Use metadata to store external IDs, flags, or references that help you search and process envelopes in your own system.

Delete metadata from an envelope

Use Swagger UI to remove metadata with the envelope metadata delete endpoint.

Delete selected keys by sending them as query parameters:

?key=customerId&key=approved

Delete all metadata by sending the delete request without query parameters.

Add metadata to an envelope form

Include the metadata object in the form payload when you create or update a form.

Example form payload

{
  "name": "Sales agreement form",
  "templateUuid": "56cacd6a-ffe7-4b77-9c0c-f928d9a18cb5",
  "metadata": {
    "source": "website",
    "campaign": "spring-2026",
    "priority": true
  }
}

Every envelope created from this form will inherit the same metadata values.

To change or remove form metadata, update the form and overwrite the metadata object.

Metadata rules

Use these limits for envelope and form metadata:

key length: 1–32 characters
value length: 0–128 characters
supported value types: string, boolean, null

To delete specific metadata entries from an envelope, send a DELETE request with query parameters such as &key=additionalProp1&key=additionalProp2. To delete all envelope metadata, send the DELETE request without query parameters. To update or delete metadata in a form, overwrite the metadata through the regular form update endpoint.

Metadata created from templates

Use the template info section to allow metadata display in envelopes created from a template.

<metadata show="true" />

Add the metadata element to the template info section and set show="true" to allow metadata display in envelope details.

If the metadata element is missing, or if show is set to false, DocStudio does not show envelope metadata.

Display conditions

DocStudio shows the metadata block only when both conditions are met:

The template contains <metadata show="true" />.
The envelope contains at least one metadata value.

If envelope metadata is empty, DocStudio does not show the metadata block.

Fill metadata from automation

Use the following target template to fill envelope metadata in automation with "type": "envelope-initiator":

/envelope/info/metadata/map/{key}

Replace {key} with the metadata key.

Example:

/envelope/info/metadata/map/customerId

This target adds the customerId key to the envelope metadata map.

Metadata value format

Store metadata as key-value pairs.