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:

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

Topic filters are available on request. Contact support at [e-mail] to enable this feature for your account.

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

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:

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

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

Try It

Try this example in Postman using your test API key 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, including all formatting rules and webhook filter configuration.
• Learn more about metadata, including limits and additional usage examples.
• Set up webhooks to receive real-time envelope events in your backend.