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.

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

{
  "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:

Header	Required	Description
Authorization	Yes	Bearer authorization token
Content-Type	Yes	Use application/json
Mailbox	Yes	Mailbox context header with the current mailbox UUID

Path parameters:

Parameter	Type	Required	Description
id	UUID	Yes	Envelope ID

Request body:

{
  "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:

Header	Required	Description
Authorization	Yes	Bearer authorization token
Mailbox	Yes	Mailbox context header with the current mailbox UUID

Path parameters:

Parameter	Type	Required	Description
id	UUID	Yes	Envelope ID

Query parameters:

Parameter	Type	Required	Description
key	array of strings	No	Metadata key or keys to delete; omit this parameter to delete all envelope metadata

Delete selected metadata keys:

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

Delete all envelope metadata:

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.

{
  "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:

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

• API tokens

• passwords

• private keys

• access credentials

• full personal records

• 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

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.

Related topics

• Send Envelope

• Check Envelope Status

• Working with XML payloads

• Working with templates and reusable IDs