Integration metadata

When your application creates documents through DocDealer, store your own identifiers in metadata. For example, associate a document with an expediente:

{
  "source": "case-manager",
  "expediente": { "id": "EXP-123" }
}

Templates and documents each have an independent object. Documents do not inherit template metadata. Template metadata belongs to the template itself, so updating it does not require publishing a new version.

Metadata is opaque integration data: it does not enter prompts, forms, rules or generated document text. It has the resource's normal read/write permissions; content locks and section regeneration protection do not block it.

Create and read

Pass optional metadata when creating a resource. Omission means {} and the initial metadataVersion is 1. The root must be an object; nested JSON is allowed, with a maximum serialized UTF-8 size of 64 KiB. U+0000 and unpaired Unicode surrogates are unsupported by the JSON storage and are rejected in metadata keys/string values and search paths/string values with a validation error.

Persistent one-shot generation also accepts metadata when creating a document. When reusing an existing documentId, replace metadata separately with its version; supplying it to generation is rejected. Ephemeral runs cannot store it.

REST detail responses and MCP get_template / get_document return both fields. Duplicating a resource clears metadata and resets its version to 1. Template file exports exclude both fields; importing preserves metadata on an existing template, while a newly imported template starts with the defaults.

Replace with concurrency control

Read the current object and version, preserve the keys you still need, then replace the complete object:

PUT /api/documents/{documentId}/metadata
Content-Type: application/json

{
  "metadata": { "source": "case-manager", "expediente": { "id": "EXP-123" } },
  "metadataVersion": 1
}

Use PUT /api/templates/{templateId}/metadata for templates. Each successful replacement returns the object and an incremented metadataVersion. A stale version returns HTTP 409: read again and reconcile before retrying. Document text edits and template publication do not increment this separate version. Send {} as metadata to clear it. Updates do not merge keys.

In MCP, use replace_document_metadata or replace_template_metadata with the resource ID and the same payload. Read the manage-integration-metadata guide first. The older tools named update_document_metadata and update_template_metadata edit other document/template settings.

Find resources by your own identifiers

Use GET /api/documents or GET /api/templates with a JSON-encoded metadataFilters parameter and limit / offset pagination:

curl --get https://thedocdealer.com/api/documents \
  -H "Authorization: Bearer $DOCDEALER_API_KEY" \
  --data-urlencode 'metadataFilters=[{"path":["source"],"value":"case-manager"},{"path":["expediente","id"],"value":"EXP-123"}]' \
  --data-urlencode 'limit=20' \
  --data-urlencode 'offset=0'

MCP list_documents and list_templates accept metadataFilters directly as an array. Filters combine with AND and compare scalar values with exact types: "123" differs from 123, and null matches only an explicitly present null. Missing keys never match null.

A path is an array of object keys. ["client", "id"] addresses a nested key; ["client.id"] addresses a literal key containing a dot. Array traversal, ranges and partial text matching are unsupported.

Search respects the caller's normal organization and resource access. Metadata values need not be unique: handle zero, one or multiple matches, and use each result's DocDealer ID to read its detail. Do not silently choose the first match.