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 payloads in the data.envelope_metadata field.

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

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:

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

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

Multiple keys

{
  "title": "Investment Agreement",
  "metadata": {
    "deal_id": "DEAL-2026-0042",
    "investor_id": "INV-88421",
    "round": "Series A",
    "amount": "500000"
  }
  //...
}

Metadata vs. topics

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