> 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/api-documentation/envelope/envelope-metadata.md).

# Envelope MetaData

{% hint style="info" %}
Metadata is available only to API users and is visible only through the API.
{% endhint %}

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](https://docs.docstudio.com/en/latest/pages/api/openApi.html#tag/form-controller) and will be used in all envelopes created from such forms.

### Metadata object example

Use a JSON object with key-value pairs.

```json
{
  "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](https://support.docstudio.com/docstudio-docs/docstudio-for-developers/api-documentation/swagger-ui) to add new metadata or overwrite existing values with the envelope metadata update endpoint.

#### Example request body

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

#### How metadata looks for an API user

The API exposes metadata as part of the envelope data.

```json
{
  "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](https://support.docstudio.com/docstudio-docs/docstudio-for-developers/api-documentation/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](https://support.docstudio.com/docstudio-docs/docstudio-for-developers/api-documentation/swagger-ui) when you create or update a form.

#### Example form payload

```json
{
  "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.

### Related topics

* [Envelope Forms](https://support.docstudio.com/docstudio-docs/docstudio-for-developers/api-documentation/envelope/envelope-forms)
* [Send Envelope](https://support.docstudio.com/docstudio-docs/docstudio-for-developers/api-documentation/envelope/send-envelope)
* [Check Envelope Status](https://support.docstudio.com/docstudio-docs/docstudio-for-developers/api-documentation/api-methods/check-envelope-status)

### 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.

```xml
<metadata show="true" />
```

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

{% hint style="info" %}
If the `metadata` element is missing, or if `show` is set to `false`, DocStudio does not show envelope metadata.
{% endhint %}

### Display conditions

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

1. The template contains `<metadata show="true" />`.
2. 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.

Example:

```json
{
  "customerId": "12345",
  "department": "Sales"
}
```

In the envelope view, DocStudio shows these values as:

```
customerId: 12345
department: Sales
```

### Related topics

* [Envelope Forms](https://app.gitbook.com/o/5SQxQoWgJM8HGKMYA3IO/s/cOltVL8GwCu4tL8RwTDW/~/edit/~/changes/15/api-documentation/envelope/envelope-forms)
* [Envelope Structure](/api-documentation/envelope/envelope-structure.md)