Envelope topics

Topics are tags you assign to envelopes. They serve two purposes: filtering webhook notifications and querying envelopes by category.

You can assign up to 10 topics per envelope. Each topic must start with a lowercase letter and contain only lowercase letters, numbers, and underscores (maximum 32 characters).

Assigning topics

Set the topics property when creating an envelope:

// POST https://api.signatureapi.com/v1/envelopes
// X-API-Key: key_test_...
// Content-Type: application/json

{
  "title": "Sales Contract",
  "topics": ["sales", "q1_2026"],
  "documents": [
    //...
  ],
  "recipients": [
    //...
  ]
}

Filtering webhooks by topic

Configure a webhook endpoint in the dashboard to receive events only for envelopes with specific topics. This lets you route different envelope types to different endpoints or trigger different workflows without building complex routing logic.

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

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

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

Filtering envelopes by topic

Use the topic query parameter on the List Envelopes endpoint to retrieve envelopes for a specific topic:

// GET https://api.signatureapi.com/v1/envelopes?topic=sales
// X-API-Key: key_test_...

Topics vs. metadata

Use topics to categorize and filter envelopes within SignatureAPI. Use metadata to store information that connects envelopes to records in your own systems.