Metadata

Metadata lets you store your own identifiers on an envelope — a CRM deal id, an employee number, an order reference — so you can match envelopes and webhooks to records in your system without keeping a mapping table.

Setting metadata#

Pass a metadata object when you create an envelope, directly or from a template. It is returned on the envelope and included in every webhook about it.

{
  "title": "Consulting agreement",
  "files": [{ "name": "agreement.pdf", "content_base64": "JVBERi0xLjcK…" }],
  "recipients": [{ "name": "Maya Patel", "email": "maya@example.com" }],
  "metadata": {
    "crm_deal_id": "D-10492",
    "customer.region": "emea"
  }
}

{
  "event": "envelope.completed",
  "data": {
    "document": { "id": "9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47", "metadata": { "crm_deal_id": "D-10492" }, "…": "…" },
    "envelope": { "id": "9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47", "metadata": { "crm_deal_id": "D-10492" }, "…": "…" }
  }
}

Updating and removing keys#

Unlike other envelope settings, metadata can be changed at any time — also after sending and after completion — with PATCH/v1/envelopes/{id}. Changes are merged:

• keys you send are added or overwritten;
• a key set to null is removed;
• keys you leave out stay as they are;
• "metadata": null removes every key.

curl -X PATCH https://signkoi.com/api/v1/envelopes/9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47 \
  -H "Authorization: Bearer $SIGNKOI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "crm_stage": "signed",
      "old_ref": null
    }
  }'

Filtering by metadata#

Find envelopes by exact metadata values with metadata[key]=value on GET/v1/envelopes. With several keys, all must match.

curl -G https://signkoi.com/api/v1/envelopes \
  -H "Authorization: Bearer $SIGNKOI_API_KEY" \
  --data-urlencode "metadata[crm_deal_id]=D-10492"

Limits#

Breaking a rule returns 422 validation_failed with param naming the key.