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

# Envelope metadata

This document explains how to add, manage, display, and use envelope metadata.

### Metadata object format

Use metadata to store integration data with an envelope. Metadata does not become document content.

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

| Rule                  | Value                       |
| --------------------- | --------------------------- |
| Key length            | 1–32 characters             |
| Value length          | 0–128 characters            |
| Supported value types | `string`, `boolean`, `null` |

Use document fields for values that appear in or are validated by the document.

### Add metadata when sending an envelope

Add metadata to the `POST /api/v1/envelope/send` request body with envelope XML in `data`.

```json
{
  "data": "<envelope templateUuid=\"{templateUuid}\" templateVersion=\"{templateVersion}\">...</envelope>",
  "metadata": {
    "customerId": "C-1024",
    "crmRecordId": "CRM-77551",
    "priority": true
  }
}
```

### Update envelope metadata

Add new metadata keys or overwrite existing values.

| Method | Endpoint                         |
| ------ | -------------------------------- |
| `PUT`  | `/api/v1/envelope/{id}/metadata` |

Headers:

<table><thead><tr><th width="143.2222900390625">Header</th><th width="147.8887939453125">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>Authorization</code></td><td>Yes</td><td>Bearer authorization token</td></tr><tr><td><code>Content-Type</code></td><td>Yes</td><td>Use <code>application/json</code></td></tr><tr><td><code>Mailbox</code></td><td>Yes</td><td>Mailbox context header with the current mailbox UUID</td></tr></tbody></table>

Path parameters:

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id`      | UUID | Yes      | Envelope ID |

Request body:

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

### Status codes

| Code | Description                   |
| ---- | ----------------------------- |
| 200  | Metadata updated successfully |

The response body is empty.

### Delete envelope metadata

Delete selected metadata keys with one or more `key` parameters. Omit `key` to delete all metadata.

| Method   | Endpoint                         |
| -------- | -------------------------------- |
| `DELETE` | `/api/v1/envelope/{id}/metadata` |

Headers:

<table><thead><tr><th width="188.888916015625">Header</th><th width="107.8887939453125">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>Authorization</code></td><td>Yes</td><td>Bearer authorization token</td></tr><tr><td><code>Mailbox</code></td><td>Yes</td><td>Mailbox context header with the current mailbox UUID</td></tr></tbody></table>

Path parameters:

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id`      | UUID | Yes      | Envelope ID |

Query parameters:

<table><thead><tr><th width="115.888916015625">Parameter</th><th width="138.888916015625">Type</th><th width="106">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>key</code></td><td>array of strings</td><td>No</td><td>Metadata key or keys to delete; omit this parameter to delete all envelope metadata</td></tr></tbody></table>

Delete selected metadata keys:

```http
DELETE /api/v1/envelope/{id}/metadata?key=customerId&key=approved
Authorization: Bearer {token}
Mailbox: {mailboxUuid}
```

Delete all envelope metadata:

```http
DELETE /api/v1/envelope/{id}/metadata
Authorization: Bearer {token}
Mailbox: {mailboxUuid}
```

### Status codes

| Code | Description                   |
| ---- | ----------------------------- |
| 200  | Metadata deleted successfully |

The response body is empty.

### Read envelope metadata

There is no separate `GET metadata` endpoint. Retrieve the envelope and read its `metadata` object.

```json
{
  "envelope": {
    "uuid": "89499ba2-287d-404c-87b0-342dc5b01b6a",
    "status": "WAITING",
    "metadata": {
      "customerId": "C-1024",
      "crmRecordId": "CRM-77551",
      "priority": true
    }
  }
}
```

Use the returned values to match the envelope with records in an external system.

### Display metadata in envelope details

Add this element to the template info section:

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

Metadata appears in envelope details only when this element is present and metadata is not empty.

### Metadata in envelope forms and callbacks

Envelopes created from a form inherit its metadata. Callbacks can include this metadata for envelopes created from forms.

### What not to store in metadata

Do not store secrets, credentials, document content, files, or large data blocks in metadata.

{% columns %}
{% column %}

* API tokens
* passwords
* private keys
* access credentials
* full personal records
  {% endcolumn %}

{% column %}

* large text blocks
* document content
* files or Base64 file data
* values longer than the supported limit
* data that should be stored in a document field instead
  {% endcolumn %}
  {% endcolumns %}

{% hint style="warning" %}
Use a valid JSON object that follows metadata rules. Add `<metadata show="true" />` to display metadata. A delete request without `key` removes all envelope metadata.
{% endhint %}

### Related topics

* [Send Envelope](/api-reference/send-envelope.md)
* [Check Envelope Status](/api-reference/check-envelope-status.md)
* [Working with XML payloads](/guides/xml-payloads.md)
* [Working with templates and reusable IDs](/guides/templates-and-reusable-ids.md)