---
title: "Create Placement Note"
method: POST
path: "/api/external/v2/placements/{placement_id}/notes"
tags: ["external-v2-notes"]
---

# Create Placement Note

`POST /api/external/v2/placements/{placement_id}/notes`

Create a note on a placement, attributed to the API key's user.

Placement notes carry ``NoteType.PLACEMENT_SHARED_NOTE`` — the broker-team
outreach-context type the web app and AI recommendations also write (it is
*not* shared with the borrower or lender). Internal placement notes are
never created or exposed here. Note: the placement ``description`` field
(``PATCH /placements/<id>``) also appends a shared note on change; these
endpoints are the canonical way to manage a placement's note collection.

## Path parameters

- `placement_id` integer, required

## Request body

- CreateNoteRequest — POST /api/external/v2/{contacts|deals|placements|companies|checklist-tasks}/<id>/notes request body. Deliberately minimal (MCP-287 Phase 1): callers supply only the note text. Note type, visibility, and purpose are assigned server-side so an external caller can never create an internal-class or hidden note.
  - `text` string, required — Note text. Simple HTML formatting is preserved; dangerous markup (scripts, javascript: URLs) is stripped server-side.

## Response `201`

Successful Response

- NoteObjectResponse — OpenAPI schema for POST /api/external/v2/{contacts|deals}/<id>/notes (object envelope).
  - `request_id` string, required
  - `timestamp` string, required
  - `data` NoteResponse, required — Note shape for both list and detail responses (MCP-287 Phase 1). Deliberately minimal: note type, visibility, and purpose are internal mechanics and are not exposed externally.
    - `id` integer, required
    - `text` string, nullable, required
    - `created_by` NoteCreatedByResponse — Creator attribution — normalized to exactly the rendered fields.
      - `id` integer, required
      - `name` string, nullable
    - `created_at` union
      - string, date-time
      - string
    - `updated_at` union
      - string, date-time
      - string

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/lev/apis/lev-api.md) · [All operations](https://skmtc.net/lev/apis/lev-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lev/lev-api/versions/e1915e1423cf/schema)