Notes

Notes are timestamped text entries that can be attached to various entities in Snapbooks, such as business partners, assets, projects, and more. Notes are immutable - once created, they cannot be modified or deleted. To update or remove a note, create a new note (potentially with empty content).

This immutable design ensures a complete audit trail of all notes and changes over time.

Endpoints

List Notes

GET /api/v2/notes

Retrieves a paginated list of notes.

Query Parameters

Response

{
  "data": [
    {
      "id": 123,
      "client_account_id": 456,
      "relation_type": "businesspartner",
      "relation_id": 789,
      "content": "Discussed payment terms for Q4",
      "active_from": "2024-03-15T10:00:00Z",
      "is_internal": false,
      "created_at": "2024-03-15T09:55:00Z",
      "created_by_id": 12,
      "updated_at": "2024-03-15T09:55:00Z",
      "updated_by_id": 12
    },
    {
      "id": 124,
      "client_account_id": 456,
      "relation_type": "asset",
      "relation_id": 234,
      "content": "Maintenance required",
      "active_from": "2024-03-20T08:00:00Z",
      "is_internal": true,
      "created_at": "2024-03-15T10:30:00Z",
      "created_by_id": 1,
      "updated_at": "2024-03-15T10:30:00Z",
      "updated_by_id": 1
    }
  ],
  "meta": {
    "page": 1,
    "pages": 1,
    "per_page": 50,
    "records": 2
  }
}

Get Note

GET /api/v2/notes/{id}

Retrieves a specific note by ID.

Query Parameters

Response

{
  "id": 123,
  "client_account_id": 456,
  "relation_type": "businesspartner",
  "relation_id": 789,
  "content": "Discussed payment terms for Q4",
  "active_from": "2024-03-15T10:00:00Z",
  "is_internal": false,
  "created_at": "2024-03-15T09:55:00Z",
  "created_by_id": 12,
  "updated_at": "2024-03-15T09:55:00Z",
  "updated_by_id": 12
}

Create Note

POST /api/v2/notes

Creates a new note. This is the only way to add notes - notes cannot be updated or deleted once created.

Request Body

Example Request

{
  "client_account_id": 456,
  "relation_type": "businesspartner",
  "relation_id": 789,
  "content": "Follow up on contract renewal",
  "active_from": "2024-03-20T09:00:00Z",
  "is_internal": false
}

Response

{
  "id": 125,
  "client_account_id": 456,
  "relation_type": "businesspartner",
  "relation_id": 789,
  "content": "Follow up on contract renewal",
  "active_from": "2024-03-20T09:00:00Z",
  "is_internal": false,
  "created_at": "2024-03-15T11:00:00Z",
  "created_by_id": 12,
  "updated_at": "2024-03-15T11:00:00Z",
  "updated_by_id": 12
}

Allowed Relation Types

Notes can only be attached to the following entity types:

Validation: The system validates that:

1. The relation_type is one of the allowed types above
2. The entity with the given relation_id exists
3. The entity belongs to the specified client_account_id

Attributes

Immutability Pattern

Notes are immutable - they cannot be modified or deleted after creation. To maintain history:

To “Update” a Note

Create a new note with the updated content and a new active_from timestamp:

{
  "relation_type": "businesspartner",
  "relation_id": 789,
  "content": "Updated: Contract renewed for 2 years",
  "active_from": "2024-03-16T14:00:00Z"
}

To “Delete” a Note

Create a new note with empty content:

{
  "relation_type": "businesspartner",
  "relation_id": 789,
  "content": "",
  "active_from": "2024-03-17T10:00:00Z"
}

Viewing History

Retrieve all notes for an entity to see the complete history:

GET /api/v2/notes?relation_type=businesspartner&relation_id=789

The response will be ordered by active_from (most recent first), showing the evolution of notes over time.

User vs System Notes

User Notes (is_internal: false)

• Created by users through the UI or API
• Visible to all users with access to the entity
• Used for manual documentation and communication

System Notes (is_internal: true)

• Generated automatically by the system
• Document system actions and automated processes
• Provide audit trails for automated operations
• Still visible in the API (not hidden)

Scheduled Notes

The active_from field allows scheduling notes for future activation:

{
  "content": "Reminder: Annual review due",
  "active_from": "2024-12-01T00:00:00Z"
}

This can be used for:

• Scheduled reminders
• Future-dated documentation
• Time-based annotations

Error Responses

Example Validation Error

{
  "error": "Related BusinessPartner does not belong to this client account",
  "status": 422
}

Business Rules

1. Immutability: Notes cannot be modified or deleted after creation
2. Ownership: The related entity must belong to the specified client_account_id
3. Access Control: Users must have access to the client account to manage notes
4. Ordering: Notes are returned ordered by active_from descending (most recent first)
5. Internal Flag: The is_internal flag cannot be changed after creation
6. Relation Validation: Only specific entity types can have notes attached

Common Use Cases

1. Customer Communications: Track conversations and agreements with business partners
2. Asset Maintenance: Document maintenance schedules and service history
3. Project Documentation: Record project milestones and decisions
4. Audit Trails: System-generated notes for automated actions
5. Scheduled Reminders: Future-dated notes for upcoming tasks
6. Historical Records: Maintain complete history by creating new notes rather than editing

Best Practices

1. Use clear, descriptive content for notes
2. Set appropriate active_from dates for scheduling
3. Use empty content to indicate deletion/superseding of previous notes
4. Filter by is_internal to distinguish user vs system notes
5. Query all notes for an entity to view complete history
6. Use consistent formatting for similar types of notes
7. Leverage the immutability for compliance and auditing