Notes

A note is free-text commentary (with optional attachments) attached to a parent entity. Notes let your team record context against the things they review.

Parent scoping

Every note is scoped to a parent by a pair of fields: entityType and entityId. The parent is one of:

entityType	Parent
APPLICATION	An application
SCREENING_HIT	A screening hit
DOCUMENT	A document
WORKFLOW_VERSION	A workflow version
AUDIT_LOG	An audit entry

GET /notes lists the notes for a given parent, and POST /notes creates one under a parent. You must have access to the parent entity to read or write its notes.

Operations

Operation	Endpoint	Notes
Create	POST /notes	Under a parent (entityType + entityId)
List	GET /notes	Scoped to a parent
List by application	GET /notes/application/{applicationId}	Every note tied to an application, across its parents
Update	PATCH /notes/{noteId}	Edits content and attachments only
Delete	DELETE /notes/{noteId}	Soft delete
Bulk delete	POST /notes/bulk/delete	Soft delete up to 500 selected notes

Notes have no type or category of their own. The parent entityType is the only classifier.

A note on an audit entry writes no audit event of its own: the NOTE_CREATED, NOTE_UPDATED, and NOTE_DELETED events never fire for an AUDIT_LOG parent, or the note would add a row to the very table it annotates. The note’s own author and timestamp are the record of who annotated.

Bulk delete

POST /notes/bulk/delete accepts noteIds. It checks each note through its application, screening-hit, document, workflow-version, or audit-entry parent before writing. Missing ids return 404, ids outside the API key’s account return a generic 403, and notes on Steward-hidden applications return 404. Already-deleted owned notes are skipped without changing their deletion actor or emitting another event. Repeated ids are coalesced in request order, and the request is limited to 500 id entries before coalescing.

Listing every note on an application

GET /notes needs one parent at a time, so reading all of an application’s commentary means one call per document and per screening hit. GET /notes/application/{applicationId} returns them in a single cursor-paginated feed instead: the application’s own notes plus the notes on its documents, on its screening hits, and on its audit entries, newest first. Notes on hidden audit entries are excluded for non-back-office callers and reappear when the entry is unhidden.

Each note in this feed carries two extra fields so you can attribute it without a second lookup:

Field	Value
sourceLabel	The document file name for a DOCUMENT note, "Screening" for a SCREENING_HIT note, the annotated event’s headline for an AUDIT_LOG note, null for APPLICATION
sourceLinkId	The document ID for a DOCUMENT note; the screened individual or business ID for a SCREENING_HIT note; the audit entry ID for an AUDIT_LOG note; else null

Pass entityTypes to narrow the feed: for example ?entityTypes=DOCUMENT,SCREENING_HIT for only the notes recorded during review. WORKFLOW_VERSION notes are account-scoped rather than application-scoped, so they never appear here.

Example

# Add a note to an application
curl -X POST https://api.getsteward.ai/api/v1/notes \
  -H "Authorization: Bearer stw_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "entityType": "APPLICATION", "entityId": "{applicationId}", "content": "Verified against the registry." }'

# List a parent entity's notes
curl "https://api.getsteward.ai/api/v1/notes?entityType=APPLICATION&entityId={applicationId}" \
  -H "Authorization: Bearer stw_live_your_api_key_here"

# List every note tied to an application, across its documents and screening hits
curl "https://api.getsteward.ai/api/v1/notes/application/{applicationId}" \
  -H "Authorization: Bearer stw_live_your_api_key_here"

Environment: Examples use Production (https://api.getsteward.ai) with an stw_live_… key. For Sandbox, use https://api.steward-sandbox.com with an stw_test_… key.