Partially update document
How partial updates work: Only fields provided in the request body will be updated. All other fields remain unchanged. This allows flexible updates without needing to send the entire document.
Content updates:
- If description or customEditorContent is provided, it replaces the existing content
- If set to null or empty string, the content is cleared
- If omitted, existing content is preserved
- Content accepts HTML or Markdown and is converted to internal format
Custom variables:
- If customVariables array is provided, it completely replaces all existing custom variables
- If omitted, existing custom variables are preserved
- To update individual variables, include all variables (updated and unchanged) in the array
Validation:
- Project version (if provided) must exist and belong to the project
- Contact person (if provided) must be available for this project type
- All provided custom variables must have valid values matching their types
Common update scenarios:
- Change document status (e.g., Draft → Waiting for Approval)
- Update document title or description
- Modify custom variable values
- Change contact person assignment
- Update layout options (table of contents, title page, etc.)
- Switch to a different project version
What is returned: The updated document with all fields, including converted HTML content and custom variable values.
/projects/{projectId}/documents/{id}AuthorizationOAuth2 access token · headerrequiredapi:writeAuthorizationBearer token (JWT) · headerrequiredprojectIdstringrequiredProject ID
idstringrequiredDocument ID
fieldsToReturnstringComma-separated list of top-level response fields to return. Overrides the endpoint compact default unless responseShape=full is used.
responseShapestringAdvanced override. Omit for the endpoint compact default. Use full only when you need the complete endpoint response, including nested fields that are not selectable with fieldsToReturn.
compactfullLT-Response-ShapestringAdvanced override. Set to full only when you need the complete endpoint response, including nested fields that are not selectable with fieldsToReturn.
fullapplication/jsonbreakdownLevelstringControls how project components are broken down in the document. Complete: Shows all levels (Components → Epics → Work Packages). UpToEpics: Shows Components with totals and Epics with their effort. NoBreakdown: Shows only Components with total price/hours. Applies to both Letter and Document styles.
CompleteUpToEpicsNoBreakdowncontactUserIdstringThe user ID of the contact person who will receive this document. This person appears as the addressed recipient in the document header and recipient fields. Must be from the list of available contact persons for this project (use GET /projects/:id/documents/contact-persons). For external projects, must be an organization member. For internal projects, must be a workspace employee.
customEditorContentstringAccepts Markdown or HTML for complex formatting. This content is rendered by the Leadtime rich editor, not by a plain Markdown viewer.
For quick/simple text, Markdown is acceptable. For polished user-facing content from an agent or integration, prefer structured HTML because it preserves editor blocks, links, and layout more predictably.
Use only the nodes and marks documented below for this field. Supported editor features differ by endpoint and field. Choose formatting for readability, not decoration: use headings for real sections, paragraphs for narrative text, lists or tables for structured facts, blockquotes for quoted context, callouts for important outcomes/risks/notes when supported, and explicit anchors for links. Do not rely on bare URLs or Markdown links when the link must be clickable; use explicit anchors such as <a href="https://example.com" target="_blank" rel="noopener noreferrer nofollow">link text</a>.
In HTML you can use:
Node Types and Marks
Nodes
paragraph Type: block Content: inline* (inline only — do not use block tags such as <p> inside; use e.g. <br>, <strong>, <em>, <span>…) Default paragraph. extraPlaceholder is an internal structure for the editor to show a ghost placeholder in empty “template” lines (ProseMirror JSON fragment or null). For normal agent output leave extraPlaceholder as null. Only set it if you are intentionally mirroring a field placeholder the user already has in the open editor; do not set random placeholder data for free-form answers. Atts:
- extraPlaceholder: null
<p class="paragraph-base" extraplaceholder="null/some-value"></p>
heading Type: block Content: inline* (inline only — do not use block tags such as <p> inside; use e.g. <br>, <strong>, <em>, <span>…) Atts:
- level: 1
<h1 class="heading-base"></h1>
bulletList Type: block list Content: listItem+ Atts: none
<ul class="list-base"><li></li></ul>
hardBreak Type: inline Atts: none
<br>
horizontalRule Type: block Atts: none
<hr class="hr-base">
orderedList Type: block list Content: listItem+ Atts:
- start: 1
- type: null
<ol class="order-list-base" type="null/some-value"><li></li></ol>
listItem Content: (paragraph|list)* (paragraphs and/or lists, in any order) Atts: none
<li></li>
blockquote Type: block Content: block+ (one or more block child nodes (e.g. paragraph, list, …)) Atts: none
<blockquote class="blockquote-base"><p class="paragraph-base"></p></blockquote>
table Type: block Content: tableRow+ Atts: none
<table style="width: 0px;"><colgroup></colgroup><tbody><tr></tr></tbody></table>
tableRow Content: (tableCell | tableHeader)* Atts: none
<tr></tr>
tableHeader Content: block+ (one or more block child nodes (e.g. paragraph, list, …)) Atts:
- colspan: 1
- rowspan: 1
- colwidth: null
- align: null
<th colspan="1" rowspan="1" colwidth="null/some-value" style="text-align: null/some-value;"><p class="paragraph-base"></p></th>
tableCell Content: block+ (one or more block child nodes (e.g. paragraph, list, …)) Atts:
- colspan: 1
- rowspan: 1
- colwidth: null
- align: null
<td colspan="1" rowspan="1" colwidth="null/some-value" style="text-align: null/some-value;"><p class="paragraph-base"></p></td>
variable Type: inline Document/template variable token (span with data-type="variable" and data-id).
- id: Variable key, often scoped (e.g. currentUser.firstName, project.name). Only use keys that exist for the document type you are in; product docs list the allowed variable ids. Do not invent new variable names in HTML for production templates. Atts:
- id: null
<span data-type="variable" data-id="null/some-value" id="null/some-value"></span>
pageBreak Type: block Page break for PDF/print output (void <page-break> element). Inserts a hard page break when exporting. Use sparingly where the user asked for a new printed page, not for normal on-screen line breaks (use hardBreak/paragraphs instead). Atts: none
<page-break></page-break>
condition Type: block Content: conditionBody (a single condition body block) This node conditionally renders its content based on a set of rules. The rules are defined in the 'conditions' attribute. 'conditions' is an object like: { type: 'and' | 'or', expressions: Array<Expression | ConditionGroup> }. An 'Expression' is { field: string, operator: string, value: any }. A 'ConditionGroup' is a nested { type: 'and' | 'or', expressions: [...] }. Example for an expression: { field: 'invoice.total', operator: 'gt', value: 100 } means 'if invoice total is greater than 100'. Supported operators typically include: eq (equals), neq (not equals), gt (greater than), gte (greater than or equal to), lt (less than), lte (less than or equal to), contains, in, is_true, is_false, etc. Check editor UI for available fields and operators. ALL FIELDS CAN ONLY BE EXISTING VARIABLES. DO NOT INVENT NEW FIELDS. Atts:
- conditions: { "type": "and", "expressions": [] }
<condition conditions="{"type":"and","expressions":[]}"><condition-body><p class="paragraph-base"></p></condition-body></condition>
conditionBody Content: block+ (one or more block child nodes (e.g. paragraph, list, …)) Atts: none
<condition-body><p class="paragraph-base"></p></condition-body>
Marks
link Atts:
- href: null
- target: _blank
- rel: noopener noreferrer nofollow
- class: null
- title: null
<a target="_blank" rel="noopener noreferrer nofollow" href="">link text example</a>
bold Atts: none
<strong>bold text example</strong>
code Atts: none
<code>code text example</code>
italic Atts: none
<em>italic text example</em>
strike Atts: none
<s>strike text example</s>
underline Atts: none
<u>underline text example</u>
Available Template Variables
You can use the following variables in your document templates. Variables are represented as HTML spans:
workspace: workspace.vat, workspace.hourRate, workspace.invoiceDaysTillOverdue, workspace.standardReminderFee, workspace.baseInterestRate, workspace.interestRate
company: company.companyName, company.legalForm, company.country, company.zip, company.city, company.street, company.houseNumber, company.phone, company.email, company.website, company.fax, company.taxNumber, company.registrationNumber, company.registrationCourt
organization: organization.companyName, organization.shortName, organization.legalForm, organization.description, organization.country, organization.zip, organization.city, organization.street, organization.houseNumber, organization.phone, organization.email, organization.website, organization.fax, organization.taxNumber, organization.registrationNumber, organization.registrationCourt, organization.hourRate, organization.invoiceDaysTillOverdue, organization.standardReminderFee, organization.baseInterestRate, organization.interestRate
project: project.name, project.category, project.status, project.defaultAccountable, project.country, project.projectId, project.activeVersionId, project.activeVersionName
currentUser: currentUser.title, currentUser.degree, currentUser.email, currentUser.firstName, currentUser.lastName, currentUser.country, currentUser.zip, currentUser.city, currentUser.street, currentUser.houseNr, currentUser.birthday, currentUser.phone, currentUser.signature
recipient: recipient.firstName, recipient.lastName, recipient.position, recipient.gender, recipient.title, recipient.degree, recipient.birthdate, recipient.activeVersionName, recipient.country, recipient.zip, recipient.city, recipient.street, recipient.houseNumber, recipient.phone, recipient.email, recipient.socialNetwork
macros: macros.todaysDate, macros.dearCustomer
Example HTML: <span data-type="variable" data-id="currentUser.firstName">John</span>, <span data-type="variable" data-id="project.name">Website Redesign</span>
customVariablesDocumentCustomVariableDto[]Array of custom variables defined for this document. Custom variables allow you to add project- or template-specific values that are not covered by standard system variables (like client name, project budget, contract duration, etc.). Each variable has a name, type, value, and optional description. Variables can be referenced in document templates using the syntax: custom.variable_name. If the document template includes custom variables, you must provide values for all required variables.
Show propertiesHide properties
DocumentCustomVariableDtodescriptionstringHuman-readable label/description for this variable. This is displayed to users when they are prompted to fill in the variable value when generating a document.
idstringVariable ID (UUID). Only required when updating an existing variable. Omit when creating a new variable.
namestringrequiredVariable name/key used to reference this variable in the template content. Use lowercase with underscores (e.g., "client_name", "project_budget"). This name is used in the variable reference: custom.variable_name.
optionsstring[]Available options for Select or MultiSelect variable types. For Select, users choose one option. For MultiSelect, users can choose multiple options. This field is ignored for other variable types.
requiredbooleanWhether this variable must be filled in when generating a document from the template. If true, users cannot proceed without providing a value. If false, the variable is optional.
typestringrequiredThe data type of this variable. Determines what kind of input is expected and how the value is validated. Available types: Text (short text), LongText (multi-line text), Number (numeric value), Date (date/time), Boolean (true/false), Select (single choice from options), MultiSelect (multiple choices from options).
TextLongTextNumberDateBooleanSelectMultiSelectvaluestring | number | boolean | string[]Default value for this variable. The type of value depends on the variable type: - Text/LongText/Select: string
- Number: number
- Boolean: boolean
- Date: ISO 8601 date string (e.g., "2024-01-15")
- MultiSelect: array of strings
This value is pre-filled when generating a document, but users can override it.
Show propertiesHide properties
stringnumberbooleanstringstringdescriptionstringOptional document description or introduction text. Accepts HTML or Markdown format - will be automatically converted to internal IDoc format for storage. Supports rich formatting: headings, lists, tables, links, bold, italic. When retrieved via GET, content is returned as HTML for easy display.
documentStylestringThe document layout style. Letter: Invoice-like layout suitable for direct mailing. Document: Traditional multi-page document with TOC. Only applies to Estimate type documents. Defaults to Letter for new documents.
LetterDocumentheadingStylestringControls how headings are automatically numbered in the document. Normal: No automatic numbering. Sequential: Numbered from level 1 (1, 1.1, 1.1.1). SequentialFromSecondLevel: Numbering starts from level 2 (H1 unnumbered, then 1.1, 1.1.1). SequentialWithParagraphs: Same as SequentialFromSecondLevel but with paragraph sign prefix (§ 1, § 1.1). Important for legal documents and contracts. Numbering is dynamic and adjusts when conditional sections are shown/hidden.
NormalSequentialSequentialFromSecondLevelSequentialWithParagraphsincludeTocbooleanWhether to include an automatically generated table of contents in the document. The TOC is built from document headings and appears at the beginning of the document. Useful for longer documents with multiple sections. Defaults to true.
indicationModebooleanWhen enabled, marks the document as a non-binding cost indication or preliminary estimate. This is important for legal purposes to distinguish between binding offers and preliminary estimates. When false, the document is treated as a binding offer. Defaults to false.
introTextstringCustom introduction text for the offer, in HTML or Markdown format. Overrides workspace/organization defaults. Supports rich formatting and template variables. When retrieved via GET, content is returned as HTML.
languageobjectBCP 47 language tag for generated document text (e.g. de, en). When omitted or null, workspace/organization defaults apply.
outroTextstringCustom closing text for the offer, in HTML or Markdown format. Overrides workspace/organization defaults. Supports rich formatting and template variables. When retrieved via GET, content is returned as HTML.
snapshotIdstringThe project version (snapshot) ID that this document is based on. Documents are always linked to a specific project version for traceability and audit purposes. Use GET /projects/:id/versions endpoint to retrieve available versions for a project. The snapshot must exist and belong to the project.
statusstringThe workflow status of the document. Draft: Initial version, not yet finalized. WaitingForApproval: Sent to client for review. Final: Ready for signing. Accepted: Approved by client. Rejected: Declined by client. Parked: Temporarily set aside. Documents typically start as Draft and progress through the workflow.
DraftFinalWaitingForApprovalAcceptedRejectedParkedtitleobjectThe title/name of the document. This appears in document lists, headers, and exports. Should be descriptive and unique enough to identify the document. For Letter-style Estimate documents, this field is optional and will be automatically cleared (title is not used in letter format).
titlePagebooleanWhether to include a title page at the beginning of the document. The title page typically includes document title, project information, contact details, and creation date. Useful for formal documents and exports. Defaults to true.
typestringThe type/category of document. Estimate: Commercial proposals with services, quantities, and costs. Specification: Detailed requirement documents describing deliverables. CustomEditor: Free-form documents like contracts, NDAs, or custom agreements that can use templates with variables.
EstimateSpecificationCustomEditorvalidUntilstring<date-time>The date until which this offer is valid. Used for Letter-style offers to indicate expiration date. Defaults to one month from creation date if not specified.
Document updated successfully
breakdownLevelstringrequiredComponent breakdown level
CompleteUpToEpicsNoBreakdowncontactUserIdstringrequiredThe user ID of the contact person assigned to this document. This person appears as the addressed recipient in the document header and recipient fields. Empty string if no contact person is assigned.
createdAtstring<date-time>requiredISO 8601 timestamp indicating when the document was created. Used for sorting, filtering, and audit trails.
customEditorContentobjectCustom document content for CustomEditor document type, returned as HTML (converted from internal IDoc format). Contains rich formatting: headings, lists, tables, links, variables, conditional sections. Null if no custom content was provided.
customVariablesDocumentCustomVariableDto[]requiredArray of custom variables with their current values. Each variable includes its definition (name, type, description, options) and the current value formatted according to the variable type. Empty array if no custom variables are defined.
Show propertiesHide properties
DocumentCustomVariableDtodescriptionstringHuman-readable label/description for this variable. This is displayed to users when they are prompted to fill in the variable value when generating a document.
idstringVariable ID (UUID). Only required when updating an existing variable. Omit when creating a new variable.
namestringrequiredVariable name/key used to reference this variable in the template content. Use lowercase with underscores (e.g., "client_name", "project_budget"). This name is used in the variable reference: custom.variable_name.
optionsstring[]Available options for Select or MultiSelect variable types. For Select, users choose one option. For MultiSelect, users can choose multiple options. This field is ignored for other variable types.
requiredbooleanWhether this variable must be filled in when generating a document from the template. If true, users cannot proceed without providing a value. If false, the variable is optional.
typestringrequiredThe data type of this variable. Determines what kind of input is expected and how the value is validated. Available types: Text (short text), LongText (multi-line text), Number (numeric value), Date (date/time), Boolean (true/false), Select (single choice from options), MultiSelect (multiple choices from options).
TextLongTextNumberDateBooleanSelectMultiSelectvaluestring | number | boolean | string[]Default value for this variable. The type of value depends on the variable type: - Text/LongText/Select: string
- Number: number
- Boolean: boolean
- Date: ISO 8601 date string (e.g., "2024-01-15")
- MultiSelect: array of strings
This value is pre-filled when generating a document, but users can override it.
Show propertiesHide properties
stringnumberbooleanstringstringdescriptionobjectDocument description or introduction text, returned as HTML (converted from internal IDoc format). Contains rich formatting: headings, lists, tables, links. Null if no description was provided.
documentStylestringrequiredDocument layout style
LetterDocumentformattedOfferNumberobjectFully formatted offer number string. Format: [ProjectShortcode]-v[Version]-[DDMMYYYY]-[OfferNumber]. Example: WKM-1-v2-27012026-1. Only populated for Estimate type documents.
headingStylestringHeading style for document
NormalSequentialSequentialFromSecondLevelSequentialWithParagraphsidstringrequiredUnique identifier (UUID) for the document. Used to reference the document in subsequent API calls.
includeTocbooleanrequiredInclude table of contents
indicationModebooleanrequiredEnable indication mode
introTextobjectCustom introduction text for the offer, returned as HTML (converted from internal IDoc format). Null if not set.
languageobjectDocument language override (BCP 47 tag). Null when using workspace/organization default.
offerNumberobjectAuto-generated offer number (integer). Display format is computed as: [ProjectShortcode]-v[Version]-[DDMMYYYY]-[OfferNumber]. Only populated for Estimate type documents.
outroTextobjectCustom closing text for the offer, returned as HTML (converted from internal IDoc format). Null if not set.
projectIdstringrequiredThe ID of the project this document belongs to. Documents are always associated with a specific project.
snapshotIdstringrequiredThe project version (snapshot) ID that this document is based on. This ensures the document content is tied to a specific project state for traceability and audit purposes.
statusstringrequiredDocument status
DraftFinalWaitingForApprovalAcceptedRejectedParkedtitleobjectThe title/name of the document. This appears in document lists, headers, and exports. Null for Letter-style Estimate documents (title is not used in letter format).
titlePagebooleanrequiredInclude title page
typestringrequiredDocument type
EstimateSpecificationCustomEditorvalidUntilobjectThe date until which this offer is valid. Used for Letter-style offers to indicate expiration date. Null if not set.
Unauthorized - Invalid or missing authentication token
Forbidden - Insufficient API scopes or permissions
Document not found