Document lifecycle
Step-by-step control over create, generate and export, for when one-shot generation isn't enough.
Step-by-step control over the lifecycle, for when one-shot generation isn't enough — typically because you need to attach files and let DocDealer extract data from them first.
The attachment leg is covered in Attachments and OCR. If you have no attachments, skip to one-shot generation — it does the create and the generate together.
Create a document
curl -X POST https://thedocdealer.com/api/documents \
-H "Authorization: Bearer $DOCDEALER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"templateId": "<uuid>", "title": "Poder — Ana Torres", "type": "api"}'Returns { "documentId": "<uuid>", "success": true }. Omitting templateVersionId pins the document
to the template's latest published version, and a template with no published version returns 404 —
see Versioning.
Listing them back. GET /api/documents is organization-scoped for API-key callers: a key has
no user, so DocDealer lists every document in the key's organization instead, filtered by its
template allowlist. Documents your users created inside DocDealer appear alongside the ones you
created through the API — apiKeyId on each item tells them apart.
Generate
To link a document to identifiers in your own application, pass optional
metadata at creation and use Integration metadata
for version-checked replacement and searching by your external identifiers.
POST /api/documents/generate with a documentId (rather than a templateId) pushes your
formData, generates every applicable section, and renders the DOCX. See
the quickstart for the key format, and
Generation for what happens per section.
Which sections are "applicable" is decided by the template's section visibility rules, not by you.
Protect manual corrections
The section controls in Editor and Render offer explicit protection from regeneration. Protection persists across sessions and document duplication; editing text alone never enables it. Any user or integration with permission to edit content can enable or remove it.
REST exposes PATCH /api/documents/{documentId}/sections/{sectionId}/generation-lock
with { "generationLocked": true } to protect, or false to allow regeneration.
MCP uses set_document_section_generation_lock with the same fields and IDs.
First stop any running generation: protection cannot change while it runs.
Individual generation rejects a protected section. Generating all sections skips protected sections and reports which were omitted. There is no bypass option. Manual editing and validation remain available. Protection is separate from the existing section states: an edit remains pending until validated and changed form data can still make a protected section outdated.
MCP agents correct form data and attachments first, regenerate when appropriate, and edit section HTML only as a last resort, followed by validation. They change protection only on an explicit user request.
Export
POST /api/documents/{documentId}/exports re-renders stored content in another format. It takes
the document content HTML you want rendered, plus a type:
type | Returns |
|---|---|
doc | Default. A .docx byte stream. |
pdf | A .pdf byte stream. |
all | A ZIP with both plus every referenced attachment. Capped at 60 seconds. |
preview | JSON { previewUrl, filename } for an Office-Online viewer, not bytes. |
Discovering the form schema
Two ways in, depending on whether you want the shape or the state.
GET /api/templates/{templateId} returns the template including formSchema, which holds objects
(repeating groups) and fields. Each field's type tells you what a value looks like — see
Templates and the form schema.
Use this when you are building a static integration against a known template.