Create new document

Controls 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.

The 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.

Accepts 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 ```html <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 ```html <h1 class="heading-base"></h1> ``` **bulletList** Type: block list Content: listItem+ Atts: none ```html <ul class="list-base"><li></li></ul> ``` **hardBreak** Type: inline Atts: none ```html <br> ``` **horizontalRule** Type: block Atts: none ```html <hr class="hr-base"> ``` **orderedList** Type: block list Content: listItem+ Atts: - start: 1 - type: null ```html <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 ```html <li></li> ``` **blockquote** Type: block Content: block+ (one or more block child nodes (e.g. paragraph, list, …)) Atts: none ```html <blockquote class="blockquote-base"><p class="paragraph-base"></p></blockquote> ``` **table** Type: block Content: tableRow+ Atts: none ```html <table style="width: 0px;"><colgroup></colgroup><tbody><tr></tr></tbody></table> ``` **tableRow** Content: (tableCell | tableHeader)* Atts: none ```html <tr></tr> ``` **tableHeader** Content: block+ (one or more block child nodes (e.g. paragraph, list, …)) Atts: - colspan: 1 - rowspan: 1 - colwidth: null - align: null ```html <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 ```html <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 ```html <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 ```html <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": [] } ```html <condition conditions="{&quot;type&quot;:&quot;and&quot;,&quot;expressions&quot;:[]}"><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 ```html <condition-body><p class="paragraph-base"></p></condition-body> ``` ### Marks **link** Atts: - href: null - target: _blank - rel: noopener noreferrer nofollow - class: null - title: null ```html <a target="_blank" rel="noopener noreferrer nofollow" href="">link text example</a> ``` **bold** Atts: none ```html <strong>bold text example</strong> ``` **code** Atts: none ```html <code>code text example</code> ``` **italic** Atts: none ```html <em>italic text example</em> ``` **strike** Atts: none ```html <s>strike text example</s> ``` **underline** Atts: none ```html <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>`

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.

Optional 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.

The 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.

Controls 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.

Whether 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.

When 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.

Custom 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.

BCP 47 language tag for generated document text (e.g. de, en). When omitted or null, workspace/organization defaults apply.

Custom 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.

The 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.

The 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.

The 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).

Whether 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.

The 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.

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.