Notes API

External integration

Notes are activity records scoped to a contact, with optional household associations and an attachment flow that uses presigned upload URLs for direct-to-storage file delivery.

Core note endpoints

Endpoint	Purpose
`POST /api/v1/notes/contacts/{contactUuid}`	Create a note for a contact.
`GET /api/v1/notes/contacts/{contactUuid}`	List notes for a contact (paginated).
`GET /api/v1/notes/{noteUuid}`	Get a single note.
`PUT /api/v1/notes/{noteUuid}`	Update note text, associations, and attachments.
`DELETE /api/v1/notes/{noteUuid}`	Delete a note.

{
  "textContent": "<p>Client asked for an updated proposal.</p>",
  "description": "Proposal follow-up",
  "noteCreatedFor": "C019B9D0FD0E5772F9E8ED189895D40C4",
  "attachmentUrls": [],
  "associations": [
    {
      "type": "HOUSEHOLD",
      "householdUuid": "H019B9D0FD0E5772F9E8ED189895D40C4",
      "name": "Doe Family Household"
    }
  ]
}

Note response:

{
  "noteUuid": "N019B9D0FD0E5772F9E8ED189895D40C4",
  "textContent": "<p>Client asked for an updated proposal.</p>",
  "description": "Proposal follow-up",
  "noteCreatedFor": "C019B9D0FD0E5772F9E8ED189895D40C4",
  "createdBy": {
    "type": "TENANT_STAFF",
    "uuid": "TS019C06688AA57248B9EA5325DBDFC48E"
  },
  "associations": [],
  "attachments": [],
  "createdAt": "2026-04-22T09:15:00",
  "updatedAt": "2026-04-22T09:15:00"
}

Search

GET /api/v1/notes/contacts/{contactUuid}/search accepts either q or search. The search term must be between 2 and 100 characters.

GET /api/v1/notes/contacts/{contactUuid}/search?q=proposal&page=0&size=20

Attachment flow

Attachments are a three-step process: initialize the upload, upload the file directly to the returned presigned URL, then confirm the upload before referencing the file URLs in the note payload.

Step	Endpoint	Purpose
1	`POST /api/v1/notes/contacts/{contactUuid}/attachments/init`	Request upload tickets and final storage URLs.
2	Use returned presigned URL	Upload the file directly to object storage (S3).
3	`POST /api/v1/notes/contacts/{contactUuid}/attachments/confirm-upload`	Mark the uploaded files as ready to use.
Optional cleanup	`DELETE /api/v1/notes/contacts/{contactUuid}/attachments/cancel`	Delete unused uploads.
Download	`GET /api/v1/notes/{noteUuid}/attachments/download`	Retrieve attachment data for a note.

Init request body:

{
  "files": [
    {
      "fileName": "proposal",
      "extension": "pdf",
      "fileSize": 145000
    }
  ]
}

Init response (contains the presigned upload URL and the final attachment URL to store on the note):

{
  "attachmentUrls": [
    "https://storage.example.com/notes/..."
  ]
}

Attachment constraints: the init request enforces a maximum file size of 200 KB. Accepted file types: pdf, jpg, jpeg, png, svg.