> ## Documentation Index
> Fetch the complete documentation index at: https://signatureapi-daf4ee54.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Envelope metadata

> Attach custom key-value data to envelopes for internal reference IDs and tracking

The `metadata` property lets you attach custom key-value pairs to an envelope. Use it to link envelopes to records in your own systems, such as internal reference IDs, account numbers, or transaction identifiers.

Metadata is included in all API responses that return an envelope and in all [webhook](/docs/api/webhooks) payloads in the `data.envelope_metadata` field.

<Warning>Do not store sensitive information (such as bank account numbers or card details) as metadata.</Warning>

## Limits

* Up to 10 key-value pairs per envelope.
* Keys: up to 32 characters (letters, digits, and underscores).
* Values: up to 1,000 characters.

## Using metadata

Add a `metadata` object when creating an envelope:

```json theme={null}
// POST https://api.signatureapi.com/v1/envelopes
// X-API-Key: key_test_...
// Content-Type: application/json

{
  "title": "Customer Agreement",
  "metadata": {
    "user_id": "100200",
    "contract_number": "CNT-2026-001"
  },
  "documents": [
    //...
  ],
  "recipients": [
    //...
  ]
}
```

When a recipient signs, SignatureAPI sends a `recipient.completed` webhook that includes your metadata:

```json theme={null}
{
  "id": "evt_4p2oouvNvjp1I9ckgqycH2",
  "type": "recipient.completed",
  "timestamp": "2025-12-31T15:00:01.999Z",
  "data": {
    "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5",
    "envelope_metadata": {
      "user_id": "100200",
      "contract_number": "CNT-2026-001"
    }
    //...
  }
}
```

Use the metadata in webhook handlers to update records, trigger workflows, or route notifications in your system.

## Examples

<CodeGroup>
  ```json Multiple keys theme={null}
  {
    "title": "Investment Agreement",
    "metadata": {
      "deal_id": "DEAL-2026-0042",
      "investor_id": "INV-88421",
      "round": "Series A",
      "amount": "500000"
    }
    //...
  }
  ```

  ```json Webhook correlation theme={null}
  {
    "title": "Loan Application",
    "metadata": {
      "application_id": "APP-78542",
      "correlation_id": "corr_a1b2c3d4",
      "source_system": "loan-origination"
    }
    //...
  }
  ```

  ```json Customer reference theme={null}
  {
    "title": "Service Agreement",
    "metadata": {
      "customer_id": "CUST-12345",
      "contract_number": "CNT-2026-001",
      "sales_rep": "jsmith"
    }
    //...
  }
  ```
</CodeGroup>

## Metadata vs. topics

Use [topics](/docs/api/resources/envelopes/topics) to categorize and filter envelopes within SignatureAPI. Use metadata to store information that connects envelopes to records in your own systems.