---
title: "Create a Note"
method: POST
path: "/v2/notes"
tags: ["Notes"]
---

# Create a Note

`POST /v2/notes`

Create a new note. By default it is authored by the calling user; set `creator` to attribute
it to a different internal person in your organization. Notes can be attached directly to
entities (`Persons`, `Companies`, `Opportunities`), anchored to an interaction (`meeting`,
`call`, or `chat message`), or written as a reply to an existing note.

The `type` field selects the shape of the request body. AI Notetaker note types
(`ai-notetaker`, `ai-notetaker-reply`) are system-generated and cannot be created through
this endpoint.

| **`type`** | **Description** | **Required** | **Optional** |
|------------|-----------------|--------------|--------------|
| `entities` | A note attached directly to one or more entities. | `content`, and at least one of `persons` / `companies` / `opportunities`. | Any combination of `persons` / `companies` / `opportunities`. |
| `interaction` | A note anchored to a meeting, call, or chat message. | `content`, `interaction.{type,id}`. | `persons` / `companies` / `opportunities`, added as direct associations on top of the interaction's own participants. |
| `user-reply` | A reply to an existing root note. Replies have no entity associations or interaction attachment of their own. | `content`, `parent.id` (must reference an existing root note the caller can access). | None |

By default a note is authored by the calling user. To attribute a note to a different member
of your organization, set the optional `creator` field to reference that person by id. The
referenced person must be an active internal person in your organization.

By default a note's creation time is the time of the request. To backfill a historical note,
set the optional `createdAt` field to the time the note should be recorded as created.

**Body content.** `content.html` is rendered HTML that must use only the allowed tags;
submitting restricted tags, attributes, URL schemes, or mention spans will cause the request to
fail. See the request examples below for representative payloads.

## Request body

- union — Request body for creating a note. The `type` field selects between three variants: - `entities`: a note attached directly to one or more Persons, Companies, and/or Opportunities. - `interaction`: a note attached to a meeting, call, or chat message. May optionally also be associated with additional entities. - `user-reply`: a reply to an existing root note. Replies have no entity associations or interaction attachment of their own. Additional notes: - By default a note is authored by the calling user. To attribute it to another member of your organization, set `creator` to reference that person by id. The referenced person must be an active internal person in your organization. - By default a note's creation time is the time of the request. To backfill a historical note, set `createdAt` to the time the note should be recorded as created. - For enterprise customers, the visibility follows the fallback visibility behavior for the organization. - System-generated note types (`ai-notetaker`, `ai-notetaker-reply`, `email`) cannot be created here.
  - NotesEntitiesNoteToBeCreated — Request body for creating a note attached directly to one or more entities. At least one of `persons`, `companies`, or `opportunities` must include an entry, since a note of this type requires at least one attached entity.
    - `type` 'entities', required — The note type. Must be `entities` to create a note attached to only entities.
    - `content` NotesContentToBeSaved, required — The note's body content. Only `html` is supported on write; supply rendered HTML limited to the allowed tags listed below.
      - `html` string, required — The HTML content of the note. **Allowed tags (with no attributes other than those explicitly noted):** `<p>`, `<br>`, `<strong>`, `<em>`, `<u>`, `<ol>`, `<ul>`, `<li>`, `<span>` (no attributes), `<a>` (only `href` with `http`, `https`, or `mailto` URL schemes). **Restricted (any of these will cause the request to fail):** inline `style` attributes, `class` attributes, `<img>`, `<script>`, `<iframe>`, `<style>`, `<blockquote>`, `<hr>`, `<s>`, `<pre>`, `<code>`, `<font>`. **Mentions:** mention spans (`<span data-type="note-mention" ...>`) are also restricted. Mentions cannot be created or modified through this endpoint. **Anchor tag normalization:** For security, the server appends `rel="noopener noreferrer"` and `target="_blank"` to every `<a>` element before the note is saved. **Valid examples:** `<p>Quick recap of the call.</p>`, `<p>Top action items:</p><ul><li><strong>Send pricing</strong> by Friday</li><li>Follow up with <a href="mailto:jane@acme.co">Jane</a></li></ul>` **Invalid examples (will cause the request to fail):** `<p style="color:red">Hi</p>` (inline style), `<p><img src="https://example.com/x.png"></p>` (image tag), `<p><span data-type="note-mention" data-note-mention-type="person" data-note-mention-person-id="1">John</span></p>` (mention span)
    - `creator` PersonReference
      - `id` integer, required — The persons's unique identifier
    - `createdAt` string, date-time — The time to record as when the note was created. Set this to backfill historical notes with their original date. Defaults to the current time when omitted.
    - `persons` PersonReference[] — Persons to attach the note to. Each item references a Person by id.
      - `id` integer, required — The persons's unique identifier
    - `companies` CompanyReference[] — Companies to attach the note to. Each item references a Company by id.
      - `id` integer, required — The company's unique identifier
    - `opportunities` OpportunityReference[] — Opportunities to attach the note to. Each item references an Opportunity by id.
      - `id` integer, required — The opportunity's unique identifier
  - NotesInteractionNoteToBeCreated — Request body for creating a note attached to an interaction. Notes can be attached to a meeting, call, or chat message. `interaction.type` and `interaction.id` are both required and must reference a meeting, call, or chat message the caller can access. Notes of this type are anchored to a single interaction. Entity associations (`persons`, `companies`, `opportunities`) are optional and can supplement the interaction attachment as additional direct associations on top of the interaction's own participants. The interaction participants are implicitly associated with the note by virtue of the interaction attachment, so they do not need to be included in the `persons` array unless the caller wants to create additional direct associations beyond those implied by the interaction itself.
    - `type` 'interaction', required — The note type. Must be `interaction` to create an interaction note.
    - `content` NotesContentToBeSaved, required — The note's body content. Only `html` is supported on write; supply rendered HTML limited to the allowed tags listed below.
      - `html` string, required — The HTML content of the note. **Allowed tags (with no attributes other than those explicitly noted):** `<p>`, `<br>`, `<strong>`, `<em>`, `<u>`, `<ol>`, `<ul>`, `<li>`, `<span>` (no attributes), `<a>` (only `href` with `http`, `https`, or `mailto` URL schemes). **Restricted (any of these will cause the request to fail):** inline `style` attributes, `class` attributes, `<img>`, `<script>`, `<iframe>`, `<style>`, `<blockquote>`, `<hr>`, `<s>`, `<pre>`, `<code>`, `<font>`. **Mentions:** mention spans (`<span data-type="note-mention" ...>`) are also restricted. Mentions cannot be created or modified through this endpoint. **Anchor tag normalization:** For security, the server appends `rel="noopener noreferrer"` and `target="_blank"` to every `<a>` element before the note is saved. **Valid examples:** `<p>Quick recap of the call.</p>`, `<p>Top action items:</p><ul><li><strong>Send pricing</strong> by Friday</li><li>Follow up with <a href="mailto:jane@acme.co">Jane</a></li></ul>` **Invalid examples (will cause the request to fail):** `<p style="color:red">Hi</p>` (inline style), `<p><img src="https://example.com/x.png"></p>` (image tag), `<p><span data-type="note-mention" data-note-mention-type="person" data-note-mention-person-id="1">John</span></p>` (mention span)
    - `creator` PersonReference
      - `id` integer, required — The persons's unique identifier
    - `createdAt` string, date-time — The time to record as when the note was created. Set this to backfill historical notes with their original date. Defaults to the current time when omitted.
    - `interaction` union, required — A reference to the existing interaction that an interaction note will be attached to. Notes can be attached to a meeting, call, or chat message.
      - NotesMeetingReference — A reference to an existing Meeting (calendar event) that the note will be attached to. This schema describes the request-body shape for attaching a note to a Meeting. It does not create or modify the Meeting itself. The id of the meeting. This is the same identifier returned as `interaction.id` on the read response and by `GET /v2/meetings/{meetingId}`.
        - `id` integer, required — The id of the Meeting to attach the note to
        - `type` 'meeting', required — The interaction type. Must be `meeting` to reference a Meeting.
      - NotesCallReference — A reference to an existing Call that the note will be attached to. This schema describes the request-body shape for attaching a note to a Call. It does not create or modify the Call itself. The id of the call. This is the same identifier returned as `interaction.id` on the read response and by `GET /v2/calls`.
        - `id` integer, required — The id of the Call to attach the note to
        - `type` 'call', required — The interaction type. Must be `call` to reference a Call.
      - NotesChatMessageReference — A reference to an existing Chat Message (e.g. a message from a connected chat integration such as Slack) that the note will be attached to. This schema describes the request-body shape for attaching a note to a Chat Message. It does not create or modify the Chat Message itself. The id of the chat message. This is the same identifier returned as `interaction.id` on the read response and by `GET /v2/chat-messages`.
        - `id` integer, required — The id of the Chat Message to attach the note to
        - `type` 'chat-message', required — The interaction type. Must be `chat-message` to reference a Chat Message.
    - `persons` PersonReference[] — Persons to additionally attach the note to, beyond those implied by the interaction itself. Each item references a Person by id.
      - `id` integer, required — The persons's unique identifier
    - `companies` CompanyReference[] — Companies to additionally attach the note to. Each item references a Company by id.
      - `id` integer, required — The company's unique identifier
    - `opportunities` OpportunityReference[] — Opportunities to additionally attach the note to. Each item references an Opportunity by id.
      - `id` integer, required — The opportunity's unique identifier
  - NotesUserReplyNoteToBeCreated — Request body for creating a user reply to an existing note. `parent.id` is required and must reference an existing root note (not itself a reply) that the caller can access. Reply notes do not support entity associations or interaction attachments. Replies to AI Notetaker notes are also created with `type: user-reply`; the reply itself is a user-authored note, not an AI-generated one.
    - `type` 'user-reply', required — The note type. Must be `user-reply` to create a reply note.
    - `content` NotesContentToBeSaved, required — The note's body content. Only `html` is supported on write; supply rendered HTML limited to the allowed tags listed below.
      - `html` string, required — The HTML content of the note. **Allowed tags (with no attributes other than those explicitly noted):** `<p>`, `<br>`, `<strong>`, `<em>`, `<u>`, `<ol>`, `<ul>`, `<li>`, `<span>` (no attributes), `<a>` (only `href` with `http`, `https`, or `mailto` URL schemes). **Restricted (any of these will cause the request to fail):** inline `style` attributes, `class` attributes, `<img>`, `<script>`, `<iframe>`, `<style>`, `<blockquote>`, `<hr>`, `<s>`, `<pre>`, `<code>`, `<font>`. **Mentions:** mention spans (`<span data-type="note-mention" ...>`) are also restricted. Mentions cannot be created or modified through this endpoint. **Anchor tag normalization:** For security, the server appends `rel="noopener noreferrer"` and `target="_blank"` to every `<a>` element before the note is saved. **Valid examples:** `<p>Quick recap of the call.</p>`, `<p>Top action items:</p><ul><li><strong>Send pricing</strong> by Friday</li><li>Follow up with <a href="mailto:jane@acme.co">Jane</a></li></ul>` **Invalid examples (will cause the request to fail):** `<p style="color:red">Hi</p>` (inline style), `<p><img src="https://example.com/x.png"></p>` (image tag), `<p><span data-type="note-mention" data-note-mention-type="person" data-note-mention-person-id="1">John</span></p>` (mention span)
    - `creator` PersonReference
      - `id` integer, required — The persons's unique identifier
    - `createdAt` string, date-time — The time to record as when the note was created. Set this to backfill historical notes with their original date. Defaults to the current time when omitted.
    - `parent` NotesNoteReference, required — A reference to an existing note by its id.
      - `id` integer, required — The id of the referenced note

## Response `201`

Created

- union — Note model
  - NotesEntitiesNote — An abstract base class for notes
    - `id` integer, required — The id of the note
    - `content` NotesContent, required — A note content
      - `html` string, nullable, required — The HTML content of the note
    - `creator` PersonData, required
      - `id` integer, required — The persons's unique identifier
      - `firstName` string, nullable, required — The person's first name
      - `lastName` string, nullable, required — The person's last name
      - `primaryEmailAddress` string, email, nullable, required — The person's primary email address
      - `type` 'internal' | 'collaborator' | 'external', required — The person's type. `internal` - people who are users within your Affinity instance. `collaborator` - individuals outside of your company who have read-only access to specified Affinity list views and stay updated on your firm's activities. `external` - people who are not internal nor collaborators.
    - `mentions` NotesMention[], required — The mentions in the note
      - `id` integer, required — The id of the mention
      - `type` 'person', required — The type of mention
      - `person` PersonData, required
        - `id` integer, required — The persons's unique identifier
        - `firstName` string, nullable, required — The person's first name
        - `lastName` string, nullable, required — The person's last name
        - `primaryEmailAddress` string, email, nullable, required — The person's primary email address
        - `type` 'internal' | 'collaborator' | 'external', required — The person's type. `internal` - people who are users within your Affinity instance. `collaborator` - individuals outside of your company who have read-only access to specified Affinity list views and stay updated on your firm's activities. `external` - people who are not internal nor collaborators.
    - `createdAt` string, date-time, required — The date and time the note was created
    - `updatedAt` string, date-time, nullable, required — The date and time the note was last updated
  - NotesInteractionNote — An abstract base class for notes
    - `id` integer, required — The id of the note
    - `content` NotesContent, required — A note content
      - `html` string, nullable, required — The HTML content of the note
    - `creator` PersonData, required
      - `id` integer, required — The persons's unique identifier
      - `firstName` string, nullable, required — The person's first name
      - `lastName` string, nullable, required — The person's last name
      - `primaryEmailAddress` string, email, nullable, required — The person's primary email address
      - `type` 'internal' | 'collaborator' | 'external', required — The person's type. `internal` - people who are users within your Affinity instance. `collaborator` - individuals outside of your company who have read-only access to specified Affinity list views and stay updated on your firm's activities. `external` - people who are not internal nor collaborators.
    - `mentions` NotesMention[], required — The mentions in the note
      - `id` integer, required — The id of the mention
      - `type` 'person', required — The type of mention
      - `person` PersonData, required
        - `id` integer, required — The persons's unique identifier
        - `firstName` string, nullable, required — The person's first name
        - `lastName` string, nullable, required — The person's last name
        - `primaryEmailAddress` string, email, nullable, required — The person's primary email address
        - `type` 'internal' | 'collaborator' | 'external', required — The person's type. `internal` - people who are users within your Affinity instance. `collaborator` - individuals outside of your company who have read-only access to specified Affinity list views and stay updated on your firm's activities. `external` - people who are not internal nor collaborators.
    - `createdAt` string, date-time, required — The date and time the note was created
    - `updatedAt` string, date-time, nullable, required — The date and time the note was last updated
  - NotesAiNotetakerRootNote — An abstract base class for notes
    - `id` integer, required — The id of the note
    - `content` NotesContent, required — A note content
      - `html` string, nullable, required — The HTML content of the note
    - `creator` PersonData, required
      - `id` integer, required — The persons's unique identifier
      - `firstName` string, nullable, required — The person's first name
      - `lastName` string, nullable, required — The person's last name
      - `primaryEmailAddress` string, email, nullable, required — The person's primary email address
      - `type` 'internal' | 'collaborator' | 'external', required — The person's type. `internal` - people who are users within your Affinity instance. `collaborator` - individuals outside of your company who have read-only access to specified Affinity list views and stay updated on your firm's activities. `external` - people who are not internal nor collaborators.
    - `mentions` NotesMention[], required — The mentions in the note
      - `id` integer, required — The id of the mention
      - `type` 'person', required — The type of mention
      - `person` PersonData, required
        - `id` integer, required — The persons's unique identifier
        - `firstName` string, nullable, required — The person's first name
        - `lastName` string, nullable, required — The person's last name
        - `primaryEmailAddress` string, email, nullable, required — The person's primary email address
        - `type` 'internal' | 'collaborator' | 'external', required — The person's type. `internal` - people who are users within your Affinity instance. `collaborator` - individuals outside of your company who have read-only access to specified Affinity list views and stay updated on your firm's activities. `external` - people who are not internal nor collaborators.
    - `createdAt` string, date-time, required — The date and time the note was created
    - `updatedAt` string, date-time, nullable, required — The date and time the note was last updated
  - NotesUserReplyNote — An abstract base class for notes
    - `id` integer, required — The id of the note
    - `content` NotesContent, required — A note content
      - `html` string, nullable, required — The HTML content of the note
    - `creator` PersonData, required
      - `id` integer, required — The persons's unique identifier
      - `firstName` string, nullable, required — The person's first name
      - `lastName` string, nullable, required — The person's last name
      - `primaryEmailAddress` string, email, nullable, required — The person's primary email address
      - `type` 'internal' | 'collaborator' | 'external', required — The person's type. `internal` - people who are users within your Affinity instance. `collaborator` - individuals outside of your company who have read-only access to specified Affinity list views and stay updated on your firm's activities. `external` - people who are not internal nor collaborators.
    - `mentions` NotesMention[], required — The mentions in the note
      - `id` integer, required — The id of the mention
      - `type` 'person', required — The type of mention
      - `person` PersonData, required
        - `id` integer, required — The persons's unique identifier
        - `firstName` string, nullable, required — The person's first name
        - `lastName` string, nullable, required — The person's last name
        - `primaryEmailAddress` string, email, nullable, required — The person's primary email address
        - `type` 'internal' | 'collaborator' | 'external', required — The person's type. `internal` - people who are users within your Affinity instance. `collaborator` - individuals outside of your company who have read-only access to specified Affinity list views and stay updated on your firm's activities. `external` - people who are not internal nor collaborators.
    - `createdAt` string, date-time, required — The date and time the note was created
    - `updatedAt` string, date-time, nullable, required — The date and time the note was last updated
  - NotesAiNotetakerReplyNote — An abstract base class for notes
    - `id` integer, required — The id of the note
    - `content` NotesContent, required — A note content
      - `html` string, nullable, required — The HTML content of the note
    - `creator` PersonData, required
      - `id` integer, required — The persons's unique identifier
      - `firstName` string, nullable, required — The person's first name
      - `lastName` string, nullable, required — The person's last name
      - `primaryEmailAddress` string, email, nullable, required — The person's primary email address
      - `type` 'internal' | 'collaborator' | 'external', required — The person's type. `internal` - people who are users within your Affinity instance. `collaborator` - individuals outside of your company who have read-only access to specified Affinity list views and stay updated on your firm's activities. `external` - people who are not internal nor collaborators.
    - `mentions` NotesMention[], required — The mentions in the note
      - `id` integer, required — The id of the mention
      - `type` 'person', required — The type of mention
      - `person` PersonData, required
        - `id` integer, required — The persons's unique identifier
        - `firstName` string, nullable, required — The person's first name
        - `lastName` string, nullable, required — The person's last name
        - `primaryEmailAddress` string, email, nullable, required — The person's primary email address
        - `type` 'internal' | 'collaborator' | 'external', required — The person's type. `internal` - people who are users within your Affinity instance. `collaborator` - individuals outside of your company who have read-only access to specified Affinity list views and stay updated on your firm's activities. `external` - people who are not internal nor collaborators.
    - `createdAt` string, date-time, required — The date and time the note was created
    - `updatedAt` string, date-time, nullable, required — The date and time the note was last updated

## Other responses

- `400` — Bad Request
- `403` — Forbidden
- `404` — Not Found
- `default` — Errors

---

[API](https://skmtc.net/affinity/apis/affinity-api-v2.md) · [All operations](https://skmtc.net/affinity/apis/affinity-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/affinity/affinity-api-v2/revisions/4c2891c31b7f/schema)