---
title: "Create a note"
method: POST
path: "/v1/households/{household_id}/notes"
tags: ["Notes"]
---

# Create a note

`POST /v1/households/{household_id}/notes`

## Request

- Base URL: `https://api.slant.app`
- URL: `https://api.slant.app/v1/households/{household_id}/notes`
- Auth: HTTP bearer

Create a new note for a household. Notes use a wrapped body; the required field is note.content: { "note": { "content": "..." } }.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `note` object, required
    - `content` string, required: Plaintext or markdown content. HTML tags are stripped.
    - `pinned` boolean: Whether the note is pinned
    - `tag_ids` string[]: Complete set of note label IDs. Pass an empty array to clear all labels.
    - `references` object[]: Complete set of referenced records. Pass an empty array to clear all references.
      - `id` string, required: The referenced record ID
      - `type` 'Business' | 'Client' | 'Contact' | 'Household' | 'Person' | 'Prospect' | 'Trust' | 'User', required: The referenced record type

## Response `201`

note created

- object
  - `id` string, required: The note ID
  - `content` string, required: The plaintext content of the note
  - `pinned` boolean, required: Whether the note is pinned
  - `hidden` boolean: Whether the note is hidden
  - `tag_ids` string[], required: The complete set of label IDs applied to the note
  - `references` object[], required: Records referenced by the note
    - `id` string, required: The referenced record ID
    - `type` 'Business' | 'Client' | 'Contact' | 'Household' | 'Person' | 'Prospect' | 'Trust' | 'User', required: The referenced record type
    - `label` string, required: The server-derived display label
  - `book_id` string, required: The book ID
  - `household_id` string, nullable: The household ID
  - `notable_type` string, required: The type of record the note belongs to
  - `notable_id` string, required: The ID of the record the note belongs to
  - `created_by_id` string, nullable: The ID of the user who created the note
  - `created_at` string, date-time, required: When the note was created
  - `updated_at` string, date-time, required: When the note was last updated

## Other responses

- `400`: Bad Request - malformed JSON, invalid filters, or missing required book context
- `401`: unauthorized - missing or invalid token
- `403`: Access denied. Policy and membership failures may have an empty body. A read-only personal token cannot perform writes.
- `422`: unprocessable entity - invalid payload
- `429`: An hourly API rate limit was exceeded. Wait Retry-After seconds before retrying.

## Changes

- **2026-11-03** `173c41bf6be9`: 6 info
  - added the media type `application/json` for the response with the status `403`
  - added the non-success response with the status `429`
  - removed the `invalid_json` enum value from the `error` response property for the response status `400`
  - response property `detail` list-of-types was narrowed by removing types `array` from media type `application/json` of response `400`
  - …2 more

[Operation history](https://skmtc.dev/slant/apis/slant-public-api-v1/changes/v1/households/:household_id/notes/post.md)

---

[API](https://skmtc.dev/slant/apis/slant-public-api-v1.md) - [All operations](https://skmtc.dev/slant/apis/slant-public-api-v1/llms.txt) - [OpenAPI document](https://skmtc.dev/slant/apis/slant-public-api-v1/revisions/173c41bf6be9?raw)