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

# Organize with Topics and Metadata

> Use topics and metadata together to categorize envelopes and link them to records in your own systems

Topics and metadata are two complementary tools for organizing envelopes. Topics categorize envelopes within SignatureAPI, enabling webhook filtering and targeted queries. Metadata stores custom key-value data, such as internal reference IDs or account numbers, that connects envelopes to records in your own systems.

Used together, they give you precise control over how envelopes are routed and tracked across both SignatureAPI and your external systems.

## Create an Envelope with Topics and Metadata

Set `topics` and `metadata` when creating an envelope:

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

{
  "title": "Sales Contract",
  "topics": ["sales", "q1_2026"],
  "metadata": {
    "crm_opportunity_id": "OPP-20260301",
    "account_id": "ACC-88421",
    "sales_rep": "jsmith"
  },
  "documents": [
    //...
  ],
  "recipients": [
    //...
  ]
}
```

Topics and metadata limits:

* **Topics:** up to 10 per envelope, lowercase letters, numbers, and underscores only, maximum 32 characters each, must start with a lowercase letter.
* **Metadata:** up to 10 key-value pairs, keys up to 32 characters, values up to 1,000 characters.

## Using Topics

### Filter Webhook Notifications

Configure a webhook endpoint in the dashboard to receive events only for envelopes that match specific topics. This lets you route different envelope types to separate endpoints or trigger different workflows without building custom routing logic in your backend.

For example, a company with separate sales and finance workflows can:

1. Tag sales envelopes with `sales` and finance envelopes with `finance`.
2. Configure one webhook endpoint to receive only `sales` events and another for `finance` events.
3. Each endpoint receives only the notifications relevant to its workflow.

A webhook endpoint with no topic filter receives events for all envelopes.

<Note>Topic filters are available on request. Contact support at [support@signatureapi.com](mailto:support@signatureapi.com) to enable this feature for your account.</Note>

### Query Envelopes by Topic

Use the `topic` query parameter on the [List Envelopes](/docs/api/resources/envelopes/list) endpoint to retrieve envelopes for a specific topic:

```json theme={null}
// GET https://api.signatureapi.com/v1/envelopes?topic=sales
// X-API-Key: key_test_...
```

This returns all envelopes tagged with `sales`, making it easy to pull a focused list for reporting, auditing, or processing.

## Using Metadata

Metadata is included in all API responses that return an envelope and in every webhook payload under `data.envelope_metadata`. This means you can access your custom data wherever you interact with envelope events, without making additional API calls to look up related records.

When a recipient signs, SignatureAPI sends a `recipient.completed` webhook that includes the envelope's metadata:

```json theme={null}
{
  "id": "evt_4p2oouvNvjp1I9ckgqycH2",
  "type": "recipient.completed",
  "timestamp": "2026-03-01T15:00:01.999Z",
  "data": {
    "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5",
    "envelope_metadata": {
      "crm_opportunity_id": "OPP-20260301",
      "account_id": "ACC-88421",
      "sales_rep": "jsmith"
    },
    //...
  }
}
```

Use the metadata values in your webhook handler to update the corresponding record in your CRM, trigger a downstream workflow, or route the notification to the right service.

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

## Try It

[Try this example in Postman](/docs/api/postman) using your [test API key](/docs/api/test-mode) to create a free, non-binding test envelope. Test envelopes won't send emails, but you can review them in your dashboard.

## Keep Learning

* Learn more about [topics](/docs/api/resources/envelopes/topics), including all formatting rules and webhook filter configuration.
* Learn more about [metadata](/docs/api/resources/envelopes/metadata), including limits and additional usage examples.
* Set up [webhooks](/docs/api/webhooks) to receive real-time envelope events in your backend.