You can use the envelope’s metadata parameter to attach key-value data to envelopes. You can specify up to 10 keys, each with names up to 32 long, and values up to 1,000 characters long. Metadata allows you to store additional structured information on an envelope. For example, you might store an internal reference ID or an account name. Metadata won’t be visible to your users unless you choose to display it.
Avoid storing any sensitive information (such as bank account numbers, card details, etc.) as metadata.
The metadata will be included in all API calls that return an envelope (for example Get an Envelope) and will be sent along with webhook notifications in the data.envelope_metadata field.

​
Using Metadata

Metadata is useful for storing information that does not fit within standard envelope fields but helps connect envelopes with your internal systems. For example, you can store a user’s ID as metadata when creating an envelope to link it directly to a user in your system: 
{
  "title": "Customer Agreement",
  "metadata": {
    "UserId": "100200"
  },
  ...
}
When a recipient signs a document, SignatureAPI sends a recipient.completed webhook notification that includes your metadata: 
{
  "id": "evt_4p2oouvNvjp1I9ckgqycH2",
  "type": "recipient.completed",
  "timestamp": "2025-12-31T15:00:01.999Z",
  "data": {
    "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5",
    "envelope_metadata": {
      "UserId": "100200"
    },
    ...
  }
}
You can use this metadata to update the status of thee user with ID 100200 in your database, send notification emails, or trigger automated workflows.

​
Metadata vs. Topics

SignatureAPI provides Topics to categorize envelopes and filter webhook events directly within SignatureAPI. Use Topics for internal categorization and filtering within SignatureAPI. In contrast, use metadata for storing custom details that connect envelopes to your own records.