Metadata

Metadata lets you attach arbitrary key-value pairs to any document. This data is returned in all API responses and webhook payloads — useful for correlating ZipZign documents with records in your own systems.

Adding metadata

Pass a metadata object when creating a document:

{
  "type": "signable",
  "title": "NDA",
  "content": "<p>...</p>",
  "signers": [ { "name": "Alice", "email": "alice@example.com" } ],
  "metadata": {
    "clientId": "client_789",
    "dealId": "deal_2026_042",
    "salesRep": "rep_jane",
    "region": "us-west"
  }
}

Limits

Constraint	Limit
Max pairs	50 per document
Key type	String
Value type	String
Key max length	64 characters
Value max length	512 characters

Metadata in responses

Metadata is included in every document response:

{
  "id": "doc_abc123",
  "status": "awaiting_signatures",
  "metadata": {
    "clientId": "client_789",
    "dealId": "deal_2026_042"
  }
}

Metadata in webhooks

Webhook payloads also include the full metadata object:

{
  "event": "document.completed",
  "data": {
    "id": "doc_abc123",
    "metadata": {
      "clientId": "client_789",
      "dealId": "deal_2026_042"
    }
  }
}

This lets you route events to the correct records in your system without a separate database lookup.

Use cases

Store your internal orderId, userId, or contractId
Tag documents by region, team, or campaign
Track which template or workflow created a document
Pass correlation IDs for logging and tracing

Updating metadata

You can update metadata on an existing document:

curl -X PATCH https://zipzign.com/api/documents/doc_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "clientId": "client_789",
      "stage": "executed"
    }
  }'

This replaces the entire metadata object. To preserve existing keys, include them in the update.

Updated on: 16/04/2026

Was this article helpful?

Thank you!