---
search:
  tags:
    - organizations
    - POST
seo:
  description: >-
    What this endpoint does: Creates a new formal business letter linked to…
    Reference for the POST /organizations/letters endpoint in the Leadtime
    Public API API.
sidebar:
  badge: POST
  label: Create organization letter
title: Create organization letter
type: openapi-operation
---
**What this endpoint does:**
Creates a new formal business letter linked to an organization. Letters can be addressed to the organization itself or to a specific organization member (contact person).

**Required information:**
- **Organization ID**: The organization this letter belongs to (must exist in workspace)
- **Subject**: Title or topic of the letter
- **Date of letter**: The date shown on the letter (can be backdated if needed)
- **Address type**: Choose between organization address or member's private address
- **Body content**: The letter text in HTML or Markdown format

**Optional information:**
- **Member ID**: If provided, links the letter to a specific organization member/contact person. The member must belong to the specified organization.

**Content formatting:**
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 &lt;p> inside; use e.g. &lt;br>, &lt;strong>, &lt;em>, &lt;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>
```

**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>
```

### 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 organization letter body. Variables are represented as HTML spans:

`clientCompanyName`, `contactPerson`, `senderNameAndPosition`, `senderName`, `senderPosition`, `todayDate`, `dearCustomer`, `signature`

**Example HTML**: `<span data-type="variable" data-id="clientCompanyName">ACME Corp</span>`, `<span data-type="variable" data-id="contactPerson">John Doe</span>`

**Validation rules:**
- Organization ID must exist and be accessible in your workspace
- If member ID is provided, it must belong to the specified organization
- Subject cannot be empty
- Body content cannot be empty
- Date must be a valid date

**What happens after creation:**
- Letter is saved and linked to the organization
- Letter appears in the organization's letters list
- Letter can be viewed, edited, or downloaded as PDF
- Letter body is automatically converted from HTML/Markdown to internal format (IDoc)

**Use cases:**
- Create formal correspondence with customers or partners
- Generate personalized letters using template variables
- Document business communication in a centralized location
- Track all letters sent to specific organizations or members

**Note:** Requires `writeLetters` permission on the Organizations resource.

<Operation source="api-reference" id="organizationletterscontroller-createorganizationletter" />