Help

Notes

A note is a short piece of text on one record, such as a company or a project. It records who wrote it and when. A note is as private as its record: anyone who can read the record can read, add, change and delete its notes.

The web notes screens, the MCP note tools and these endpoints run the same operations, so the same rules apply everywhere.

Endpoints

Method and path Does
GET /api/v1/notes Lists the notes on one record
GET /api/v1/notes/:id Reads one note
POST /api/v1/notes Adds a note to a record
PATCH /api/v1/notes/:id Changes a note
DELETE /api/v1/notes/:id Deletes a note
PATCH /api/v1/notes/:id/restore Restores a deleted note

Records that take notes

A record is named by record_kind and record_id.

record_kind Record
project A delivery project
opportunity An opportunity
company A company
contact A contact
location A location
invoice An invoice
credit_note A credit note
cost A cost
member A member of staff, by member id
progress_claim A progress claim
expense_claim An expense claim

project and opportunity find either kind of record, and the note shows the real kind.

Permissions

Endpoint Needs
GET api_read, and read access to the record
POST api_create, and read access to the record
PATCH and restore api_update, and read access to the record
DELETE api_delete, and read access to the record

Read access follows the record’s own rules in Drum. For example, a company needs read_companies, and a member needs read_account_users. A note can be changed or deleted by anyone with read access to its record, not only its author.

A note, or a record, that the token’s user cannot read returns 404, the same as one that does not exist. A note on a deleted record also returns 404.

The note object

{
  "id": 6120,
  "record_kind": "company",
  "record": {"id": 789, "name": "Acme Corporation"},
  "content": "Prefers invoices by email. Accounts close on the 25th.",
  "financial": false,
  "ai_generated": false,
  "author": {"id": 4821, "name": "Jordan Reed"},
  "deleted": false,
  "created_at": "2026-10-02T23:41:09Z",
  "updated_at": "2026-10-02T23:41:09Z"
}
Field Meaning
record_kind, record The record the note is on. record is {id, name}
content The whole text
financial true for a comment on the Cost vs Invoiced report, an invoice or a credit note
ai_generated true when Drum’s own AI features wrote the note. Notes added through this API are false
author {id, name} of the member who wrote it. id is null when that person is no longer a member
deleted true for a deleted note

List notes

GET /api/v1/notes lists the notes on one record, newest first. Paginated (see Pagination).

Parameter Required Meaning
record_kind Yes See Records that take notes
record_id Yes The record’s id
deleted No true lists deleted notes only. Otherwise deleted notes are left out 
curl -H "Authorization: Bearer $DRUM_API_TOKEN" \
  "https://app.getdrum.com/api/v1/notes?record_kind=company&record_id=789"

Returns 200 with an array of note objects.

Read a note

GET /api/v1/notes/:id returns one note object. A deleted note is returned too, with "deleted": true.

Add a note

POST /api/v1/notes adds a note. The token’s user is the author. Send the fields flat or under note.

Field Required Rules
record_kind Yes See Records that take notes
record_id Yes The id of a kept record the token’s user can read
content Yes Up to 10,000 characters. Not blank. Surrounding spaces are removed
financial No true or false (default). true only on a project, invoice or credit_note
idempotency_key No 1 to 255 characters. Always send it at the top level, even when the other fields are under note 
POST /api/v1/notes
{
  "note": {
    "record_kind": "company",
    "record_id": 789,
    "content": "Prefers invoices by email. Accounts close on the 25th."
  },
  "idempotency_key": "crm-note-20261002-1"
}

Returns 201 with the note object.

Idempotency key. A retry with the same idempotency_key and the same fields adds nothing and returns 200 with the first note and "replayed": true. This key is a body field, not the Idempotency-Key header. The other rules match Idempotency keys. When the first note has since been deleted, a retry returns 409 idempotent_record_deleted.

Change a note

PATCH /api/v1/notes/:id changes the fields you send. Send them flat or under note. A note cannot move to another record.

Field Rules
content Replaces the whole text. Up to 10,000 characters. Not blank
financial true or false. null means false. true only on a project, invoice or credit_note 
PATCH /api/v1/notes/6120
{"content": "Prefers invoices by email to accounts@acme.example. Accounts close on the 25th."}

Returns 200 with the note object. A deleted note returns 404 note_not_found. Restore it first.

Delete and restore a note

DELETE /api/v1/notes/:id deletes the note. Returns 200 with the note object, now with "deleted": true. A note that is already deleted returns 404 note_not_found.

PATCH /api/v1/notes/:id/restore restores a deleted note. Returns 200 with the note object. A note that is not deleted returns 404 note_not_found.

Errors

Status code When
403 not_authorized The token’s user may not add or change notes on this record
404 note_not_found The note does not exist, is in another account, is on a deleted or hidden record, or is not in the state the request needs
404 project_not_found, opportunity_not_found, company_not_found, contact_not_found and the other <record_kind>_not_found codes The record does not exist, is deleted, or is hidden
409 idempotency_key_reused, retry_later, idempotent_record_deleted See Idempotency keys
422 missing_input record_id or content is missing, or content is blank
422 invalid_input A value could not be read, such as a missing or unknown record_kind, or financial: true on a record that does not take it. field names it
422 validation_failed The note would not save. errors lists why