Template types

Three families, one generation call

Every template carries a category: custom, fillable_form, or workflow. Once published, all three are listed by GET /api/v1/templates, read by GET /api/v1/templates/:id, and generated from with the same POST /api/v1/document_requests payload shape. The index and show endpoints never filter by category. What differs sharply is how each one is authored, and how much of that authoring the classic API exposes.

Custom (category: "custom")

A freeform HTML template: you control every element of the layout, and you define every variable yourself.

• What it's for: any document you want to design yourself. The layout is not constrained by an existing file.
• Authored: in the dashboard's online HTML editor, or through the API's content and variables_attributes fields.
• Through the API: full CRUD, publish/unpublish, and full CRUD on its variables. This is the only category the classic API can create.

See Templates API and Variables API.

Fillable form (category: "fillable_form")

A template backed by an uploaded PDF that already carries form fields (AcroForm widgets): text inputs, checkboxes, radio groups, drop-downs.

• What it's for: reusing an existing PDF layout (a regulated form, a document that already has its final design) instead of rebuilding it as HTML.
• Authored: by uploading the PDF from the dashboard. Doclift extracts every form field into a variable: title is the field's technical name, description is the field's label (falling back to the technical name), field_type and allowed_values are inferred from the PDF widget, and seed_value comes from the field's default value, if any. Re-uploading a new version of the PDF resyncs the variables: new fields become new variables, and fields no longer present are destroyed. From the dashboard you can edit only a variable's description and seed_value; its title and field_type always mirror the PDF and cannot be renamed or retyped by hand.
• Through the API: read-only. GET /api/v1/templates and /:id return it once published, with its auto-detected variables embedded in the show response. POST /api/v1/document_requests generates from it exactly like a custom template. Nothing else: no create, update, delete, publish/unpublish, or variables endpoint accepts it.

See Fillable forms for the full generation and variable-mapping reference.

Workflow (category: "workflow")

A tree of sections (nested groups and content blocks, each with its own condition) instead of one HTML blob. It has its own API, mounted entirely under /api/v1/workflows/*: templates, sections, variables, theme, and publication are all separate resources there. The classic /api/v1/templates write endpoints never touch a workflow.

• What it's for: documents assembled from many conditionally-included parts (long contracts, multi-scenario documents) where you need structure the single-blob HTML editor does not give you.
• Authored: entirely through the workflow API (or the dashboard's workflow builder); the classic API cannot create, edit, or delete a workflow template.
• Through the classic API: the same read-only and generate-only access as fillable_form. GET /api/v1/templates and /:id list and show it once published, and POST /api/v1/document_requests generates from it.