Merge tags

Merge tags are the data contract between a template and its callers. A field with "merge_tag": "client_name" takes its value from data.client_name at generation time; the version's merge_tags array declares what each tag means.

Derived and declared

Any tag referenced by a field is derived automatically into the version's schema. Explicit declarations refine a derived tag (its type, whether it is required, an example, a description) for validation and discovery:

{
  "fields": [
    { "type": "text", "merge_tag": "client_name", "x": 90, "y": 200, "width": 300, "height": 20 }
  ],
  "merge_tags": [
    { "tag": "client_name", "type": "string", "required": true,
      "example": "Jordan Smith", "description": "Full name as it appears on the case" }
  ]
}

GET /v1/templates/{templateId}/versions/{version} returns the full merge-tag schema. An integration can discover exactly what data a template needs without reading its layout.

Tag names match ^[a-zA-Z0-9_.-]{1,64}$.

Types

Type	Value	Rendered by
string (default)	Text	text, field, fill fields
number	Numeric	Same as string, validated as a number
date	Date string (e.g. 2026-08-15)	Same as string, validated as a date
boolean	Truthy/falsy	checkbox fields check on truthy values
image	An asset id	image fields
array	A list of row objects	table fields

Types are an open set: tolerate values you don't recognize.

Validation: strict by default

Generation validates data against the version's merge-tag schema before anything renders. The default, "data_validation": "strict", rejects:

Problem	Error
A required tag is missing	422 MISSING_MERGE_TAGS
A value doesn't match its declared type	422 INVALID_MERGE_VALUES
data contains a tag the version never declared	422 UNKNOWN_MERGE_TAGS

Strict validation means a typo in a data pipeline produces a clear 422, never a notice with a blank where a hearing date should be.

"data_validation": "lenient" renders what it can and reports the rest as warnings instead. Use it for previews and migration tooling, not for production issuance.

Dry runs

"dry_run": true on a generate request validates the data and returns the result without rendering anything:

curl -s "https://api.pdfs.ecourtdate.com/v1/templates/$TEMPLATE_ID/generate" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "client_name": "Jordan Smith" }, "dry_run": true }'

{ "valid": true, "template_id": "5f0c2a4e-…", "version": 1, "warnings": [] }

Use dry runs to validate a whole batch's rows during data preparation, or as a pre-flight check in interactive flows.