Notes API

• List notes
• Get a single note
• Fields

List notes

List all notes (including the internal notes) for an account:

GET /notes

Response

Status: 200 OK

[
  {
    "person": {
      "name": "Barney Turban",
      "id": 58
    },
    "created_at": "2016-03-12T11:33:00-06:00",
    "text": "Use the information gathered in the previous risk & impact analysis tasks to finalize the change plan. Do this is such a way that the implementation plan minimizes both the risk of failure and the impact on the customer(s). Also ensure that the necessary approvals are collected before the implementation of the change can start.\n\nNote that approval from the owner of the service that is related to the workflow is required for each non-standard change, regardless of whether customer representative approval is required or not. Approval from the customer representative(s) of the service that is related to the workflow is only required if the change implementation is going to cause:\n- the service to become unavailable or degraded during service hours, or\n- the functionality of the service to become different.",
    "id": 464,
    "medium": "default",
    "task": {
      "id": 89,
      "subject": "Finalize the change plan"
    },
    "attachments": []
  },
  {
    "person": {
      "name": "Luis Thomas",
      "id": 60
    },
    "created_at": "2016-03-12T11:33:00-06:00",
    "text": "Because the servers are monitored by NNM and because they will need to be rebooted after the upgrade, events wil be generated, and we should warn Operations.",
    "id": 463,
    "medium": "default",
    "task": {
      "id": 88,
      "subject": "Will events be generated when the change is implemented?"
    },
    "attachments": []
  },
  "..."
]

The response contains these fields by default. Filtering and pagination are available to reduce/limit the collection of notes.

Predefined Filters

The following predefined filters are available:

• /notes/public : List all public notes
• /notes/internal : List all internal notes

Collection Fields

By default all fields will appear in collections of notes.

Filtering

Filtering is available for the following fields :

id person created_at medium

Sorting

By default a collection of notes is sorted descending by id .

The following fields are accepted by the ?sort= parameter :

id person_id created_at

Get a single note

GET /notes/:id

Response

Status: 200 OK

{
  "person": {
    "name": "Patrick Spratt",
    "id": 56
  },
  "created_at": "2009-02-02T13:18:00-06:00",
  "text": "Just came out of a meeting with our CIO. The business is going quickly and he does not want IT to be a bottleneck. He wants to make sure that new servers can be added quickly as needed. The first step we need to take is to add another rack in the data center. Carla, can you please open a new workflow for this?",
  "id": 2,
  "medium": "default",
  "request": {
    "id": 68673,
    "subject": "Add new rack in data center"
  },
  "attachments": []
}

The response contains these fields .

Fields

account

Readonly reference to Account — The account that the note belongs to:

• Public notes belong to the account in which the author’s person record is registered.
• Internal notes belong to the account in which specialists are allowed to see the internal note.

attachments

Readonly aggregated Attachments

created_at

Readonly datetime — The date and time at which the note was created.

id

Readonly integer — The unique ID of the note.

inbound_email

Readonly reference to Inbound Email — The inbound email that led to the creation of this note.

internal

Optional boolean default: false — When the note is internal, the Internal field is set to true .

internal_account

Readonly reference to Account — The internal account, only present for internal notes.

medium

Readonly enum , default: default — The medium used to add the note. Valid values are:

• default : the note was manually added by a person, or automatically using the REST or Import API .
• email : the note was added by the Mail API
• outbound_email : the note was created via the “Send Email” action
• system : the note was generated by the system
• redacted : the note was deleted by an account administrator
• automation : the note was added by an automation rule

person

Required reference to Person

text

Required text (max 64KB) , default: “

Examples

Create a note with rich text formatting

The text field supports rich text formatting, including bold, italic, lists, code blocks, and expandable sections. Notes are typically created on specific records through their endpoints (e.g., /requests/:id/notes, /tasks/:id/notes).

Example with basic formatting:

POST /requests/12345/notes
Content-Type: application/json
Authorization: Bearer <token>

{
  "text": "Please review the following:\n\n* Check **error logs** for the past 24 hours\n* Verify __network connectivity__\n* Monitor `system resources`"
}

Create a note with an expandable section (spoiler)

You can use HTML5 <details> and <summary> tags to create expandable sections:

POST /requests/12345/notes
Content-Type: application/json
Authorization: Bearer <token>

{
  "text": "<details>\n<summary>Diagnostic Information</summary>\n\nPlease review:\n\n* **Log file**: /var/log/system.log\n* **Status**: Check with `systemctl status service`\n\n</details>"
}

Create multiple expandable sections

You can include multiple expandable sections in a single note:

POST /requests/12345/notes
Content-Type: application/json
Authorization: Bearer <token>

{
  "text": "<details>\n<summary>Section 1</summary>\n\nContent for the first section.\n\n</details>\n\n<details>\n<summary>Section 2</summary>\n\nContent for the second section.\n\n</details>"
}

Create an internal note with expandable sections

Internal notes are only visible to specialists and account administrators:

POST /requests/12345/notes
Content-Type: application/json
Authorization: Bearer <token>

{
  "text": "<details>\n<summary>Internal Diagnosis</summary>\n\nThis is internal information only for specialists.\n\n</details>",
  "internal": true
}