Create a note on an entity

POST /api/v1/entities/{entity_uuid}/notes operationId: note.create

Base: https://portal.watcheye.com.au/api/v1/entities/{entity_uuid}/notes

Create a new note attached to the specified entity. The note inherits the entity's program and account.

Notes created via this endpoint are attributed to the calling API key (the response created_by carries { type: "api_key", uuid, label }). They cannot be edited or deleted from the portal. Any API key on the same account can manage these notes via the PATCH and DELETE endpoints.

To attach a note to an event (rather than just to the entity) use the Events PATCH endpoint with a note field.

Idempotency

This endpoint accepts the Idempotency-Key header so that retries on network failure are safe. See the Idempotency section of the API guide for the full contract.

Path parameters

Field	Description
`entity_uuid`required	string (uuid) The entity UUID

Header parameters

Field Description

Field	Description
`Idempotency-Key`	string [max 255 characters] Optional client-generated key (typically a UUID) that lets you safely retry a write request without risk of duplicate work or duplicate billing. A retry with the same key and body returns the original response verbatim, with the `Idempotent-Replay: true` response header. Honoured on `POST` requests only. See the Idempotency section of the API guide for the full contract. Example: `8c4d3a18-2f63-4f9a-9f3a-9b1f5a7c2d4f`

Idempotency-Key

string [max 255 characters]

Optional client-generated key (typically a UUID) that lets you safely retry a write request without risk of duplicate work or duplicate billing. A retry with the same key and body returns the original response verbatim, with the Idempotent-Replay: true response header.

Honoured on POST requests only. See the Idempotency section of the API guide for the full contract.

Example: 8c4d3a18-2f63-4f9a-9f3a-9b1f5a7c2d4f

Request body

Content type application/json. The note details

Field Description

Field	Description
`note_text`required	string [max 5000 characters] Free-text content of the note. Max 5000 characters. Example: `Synced from CRM ticket`

note_textrequired

string [max 5000 characters]

Free-text content of the note. Max 5000 characters.

Example: Synced from CRM ticket

Responses

201

Note created

application/json

Field	Description
`data`	object A note attached to an entity, optionally also linked to an event. Deleting a note is a soft-delete: the record stays in the database for audit / compliance purposes but is no longer surfaced by the API. Subsequent show or list calls for a deleted note return `404`. Notes can be archived in the portal (the `archived_at` timestamp); the API surfaces this state for filtering but archive/unarchive operations are not currently exposed via the API.
`data.uuid`	string (uuid) The note's UUID Example: `7c1c0a8e-2b9f-4f0e-8d1a-1e2b3c4d5e6f`
`data.note_number`	string A short obfuscated public identifier for the note (e.g. "N-A1-B2C-3D4") Example: `N-A1-B2C-3D4`
`data.note_text`	string The free-text content of the note (max 5000 characters) Example: `Confirmed match against verified passport details.`
`data.created_by`	object or null Identifies who created the note. The `type` discriminator picks the shape of the remaining fields: `{ type: "user", uuid, username }` - a portal user created the note. The portal user (or an account manager) can edit/delete it through the portal. The API cannot edit or delete user-authored notes. `{ type: "api_key", uuid, label }` - an API key on this account created the note. The API can manage these notes via the PATCH and DELETE endpoints. The portal cannot edit or delete API-key-authored notes. `null` - rare legacy notes from before actor attribution was recorded; treat as read-only.
`data.created_by.type`	string Discriminator for the actor type. Enum: `user`, `api_key`
`data.created_by.uuid`	string (uuid) UUID of the user or API key that created the note.
`data.created_by.username`	string Username of the portal user. Present only when `type` is `user`.
`data.created_by.label`	string Label of the API key. Present only when `type` is `api_key`.
`data.is_immutable`	boolean When true, the note is an immutable audit-trail entry and cannot be edited or deleted by any actor through any channel. PATCH and DELETE requests against an immutable note return 403. Example: `false`
`data.entity_uuid`	string (uuid) UUID of the entity this note is attached to
`data.program_uuid`	string (uuid) UUID of the program the entity belongs to
`data.event_uuid`	string (uuid) or null UUID of the event this note is attached to, if any. Notes created via the Events PATCH endpoint with a `note` field carry an `event_uuid`; notes created via POST /v1/entities/{uuid}/notes do not.
`data.archived_at`	string (date-time) or null ISO 8601 timestamp at which the note was archived in the portal (null if not archived)
`data.created_at`	string (date-time) Example: `2025-01-01T00:00:00Z`
`data.updated_at`	string (date-time) Example: `2025-01-01T00:00:00Z`
`api_reference`	string (uuid)

409

Conflict - a request with this Idempotency-Key is currently being processed

application/json

Field	Description
`message`	string Example: `A request with this Idempotency-Key is already being processed.`

422

Idempotency-Key was reused with a different request body

application/json

Field	Description
`message`	string Example: `Idempotency-Key was reused with a different request body.`

Standard error responses: 400 401 403 404 429 5XX See common error responses

Previous List notes Next Show a note

Request body application/json

{
    "note_text": "Synced from CRM ticket"
}

Response

201 Note created

{
    "data": {
        "uuid": "7c1c0a8e-2b9f-4f0e-8d1a-1e2b3c4d5e6f",
        "note_number": "N-A1-B2C-3D4",
        "note_text": "Confirmed match against verified passport details.",
        "created_by": {
            "type": "user",
            "uuid": "00000000-0000-0000-0000-000000000000",
            "username": "string",
            "label": "string"
        },
        "is_immutable": false,
        "entity_uuid": "00000000-0000-0000-0000-000000000000",
        "program_uuid": "00000000-0000-0000-0000-000000000000",
        "event_uuid": "00000000-0000-0000-0000-000000000000",
        "archived_at": "2024-01-01T00:00:00Z",
        "created_at": "2025-01-01T00:00:00Z",
        "updated_at": "2025-01-01T00:00:00Z"
    },
    "api_reference": "00000000-0000-0000-0000-000000000000"
}

400 Bad Request - The request is invalid shared error response

{
    "message": "Bad Request",
    "api_reference": "00000000-0000-0000-0000-000000000000",
    "errors": {
        "data.passport_number": [
            "The passport number format is invalid."
        ]
    }
}

401 Unauthorized - the API key or account is inactive, expired, or not permitted from this IP address shared error response

{
    "message": "API Key Inactive",
    "api_reference": "00000000-0000-0000-0000-000000000000"
}

403 No access - No permission to process this request shared error response

{
    "message": "No access",
    "api_reference": "00000000-0000-0000-0000-000000000000"
}

404 Not Found - The requested resource does not exist or is not accessible by this account shared error response

{
    "message": "Entity not found",
    "api_reference": "00000000-0000-0000-0000-000000000000"
}

409 Conflict - a request with this Idempotency-Key is currently being processed

{
    "message": "A request with this Idempotency-Key is already being processed."
}

422 Idempotency-Key was reused with a different request body

{
    "message": "Idempotency-Key was reused with a different request body."
}

429 Rate limited - The request rate limit has been reached shared error response

{
    "message": "Rate limited",
    "api_reference": "00000000-0000-0000-0000-000000000000"
}

5XX Internal error - Internal system error shared error response

{
    "message": "Internal error",
    "api_reference": "00000000-0000-0000-0000-000000000000"
}