API Reference
Start typing to search…

Notes

Note Management and Communication

Endpoints for managing notes and internal communications within RoofLink. Notes are the primary communication mechanism between employees, crew members, and other team members regarding specific jobs.

Supported Note Operations

This category includes the following operations:

Querying Notes

  • List Notes: Retrieve a paginated list of notes with advanced filtering options by job, tags, recipients, read status, and more.
  • Retrieve Note: Get detailed information for a specific note including sender, recipients, message content, and tags.
  • Get Thread Structure: Retrieve the complete thread structure of a note including all replies and nested conversations in a hierarchical format.

Creating and Managing Notes

  • Create Note: Create a new note associated with a job. Notes can include recipients, tags, and optional flags for notifying sales representatives or customers.
  • Reply to Note: Reply to an existing note, creating a threaded conversation linked to the parent note.

Note Actions

  • Archive Note: Archive a note to remove it from the active list. Archived notes can be retrieved later using the deleted=true parameter.
  • Unarchive Note: Restore an archived note back to the active notes list.
  • Mark as Read: Mark a note as read by the current user. This action tracks which users have read specific notes.

Note Features

Threading and Replies

Notes support threaded conversations:

  • Parent Notes: The original note that starts a conversation
  • Reply Notes: Child notes that reference a parent note, creating a threaded structure
  • Thread Structure: Use the Get Thread Structure endpoint to retrieve the complete conversation tree with depth indicators

Tags and Categorization

Notes can be tagged with company-configured categories such as "Important", "Urgent", "Follow-up", or "Question". Tags help organize and filter notes:

  • Available tags are configured at the company level
  • Tags may be required based on company settings
  • Notes can be filtered by tags using the list endpoint
  • Multiple tags can be applied to a single note

Filtering and Search

The List Notes endpoint provides extensive filtering capabilities:

  • Job Filter: View notes for a specific job
  • Tags Filter: Find notes with specific tags (supports multiple values)
  • Search: Search within note messages and customer names
  • Recipient Filters:
    • sent_to: Find notes sent to a specific employee
    • employee: Find all notes where an employee is involved (sender, recipient, or sales rep)
  • Read Status: Filter by read/unread status
  • Archived Filter: Toggle between active and archived notes

Automatic Recipients

When creating notes, the system may automatically add recipients based on business rules:

For Crew Users

When a crew member creates a note, the system automatically adds the following users as recipients (if they exist):

  • Primary sales representative
  • Secondary sales representative
  • Project manager

For Employee Users

Employees can use the notify_rep flag to automatically add the job's sales representative to the recipients list.

Notifications

After a note is created, the system automatically sends notifications to all recipients via their configured channels:

  • Email notifications
  • SMS notifications (when enabled)
  • Push notifications (when available)

Notifications are sent asynchronously after note creation. If there are no recipients specified, no notifications are sent.

Important Notes

Immutability

Notes cannot be updated or deleted after creation. This ensures message integrity and maintains an accurate audit trail of communications. As an alternative to deletion:

  • Use the Archive action to hide notes from the active list

Archived notes can be retrieved using the deleted=true query parameter, and also un-archived using the Unarchive action.

Read Status Behavior

  • Retrieving a note does not automatically mark it as read
  • Use the Mark as Read endpoint to explicitly mark notes as read
  • Read status is tracked per user

Pagination

Note lists are paginated with:

  • Default page size: 10 items
  • Maximum page size: 10 items
  • Results include pagination metadata: count, from_index, to_index, next, previous, and next_page. See the responses page for details.
  • Notes are returned in reverse chronological order by creation date

Related Operations