> For the complete documentation index, see [llms.txt](https://docs.shortcutco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shortcutco.com/developers/api-reference/reference/objects/note.md).

# The note object

The note object in the Shortcut API - every field, an example, and the endpoints that return it.

A note on a customer, lead, job, or visit.

## Fields

| Field                 | Type                                          | Description                                                                                                                                                                                                                                                                                        |
| --------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                  | id                                            | The note's id.                                                                                                                                                                                                                                                                                     |
| `object`              | `"note"`                                      | Always `note`.                                                                                                                                                                                                                                                                                     |
| `kind`                | `pinned`, `profile`, `operational`, `visit`   | `pinned`: the note at the top of the profile (one per customer). `profile`: a note added to the profile. `operational`: the office's instruction to crews on a job or visit, with a `severity`. `visit`: a note written on a visit, such as a crew member's note from the crew app.                |
| `customerId`          | id or null                                    | The customer the note is about.                                                                                                                                                                                                                                                                    |
| `leadId`              | id or null                                    | The lead the note was written on, for notes from before the lead became a customer.                                                                                                                                                                                                                |
| `jobId`               | id or null                                    | The job an operational note is on.                                                                                                                                                                                                                                                                 |
| `visitId`             | id or null                                    | The visit an operational or visit note is on.                                                                                                                                                                                                                                                      |
| `content`             | string                                        | The note's text.                                                                                                                                                                                                                                                                                   |
| `severity`            | `normal`, `warning`, `critical` or null       | How an operational note is shown to crews.                                                                                                                                                                                                                                                         |
| `expires`             | object or null                                | For operational notes: when the note stops showing.                                                                                                                                                                                                                                                |
| `expires.kind`        | `none`, `after_visit`, `after_visits`, `date` | When the note stops showing to crews.                                                                                                                                                                                                                                                              |
| `expires.date`        | string or null                                | For `date`: the last day it shows, `YYYY-MM-DD`.                                                                                                                                                                                                                                                   |
| `expires.afterVisits` | integer or null                               | For `after_visits`: how many visits it shows on.                                                                                                                                                                                                                                                   |
| `sharedWithCustomer`  | boolean                                       | Whether the customer can see it (on their invoice or portal).                                                                                                                                                                                                                                      |
| `flaggedNegative`     | boolean                                       | Whether it marks a bad interaction, which counts toward the customer being at risk.                                                                                                                                                                                                                |
| `authorName`          | string or null                                | Who wrote it, or last changed the pinned note.                                                                                                                                                                                                                                                     |
| `writtenBy`           | `crew`, `office`                              | The writer's role, not the app they wrote from: `crew` when the person who wrote it is a crew member (the employee role), `office` for anyone else. An owner who types a note in the crew app reads `office`. An instruction the office gives crews (a note with a `severity`) is always `office`. |
| `createdAt`           | timestamp                                     | When it was written, ISO 8601 in UTC.                                                                                                                                                                                                                                                              |
| `updatedAt`           | timestamp                                     | When it last changed, ISO 8601 in UTC.                                                                                                                                                                                                                                                             |

## Example

```json
{
  "id": "e4fdac7d-e147-47c4-8d92-230bd9dc5e52",
  "object": "note",
  "kind": "pinned",
  "customerId": "bee7c3c5-bb31-4f0c-877c-3a53b3c6759a",
  "leadId": "a06f27e7-9cb9-432e-8903-9e75954dd9bc",
  "jobId": "5f4ce024-5b97-4b6b-87e1-56b2542b91f9",
  "visitId": "dbf8aa40-d842-4587-848d-20ced0d75c15",
  "content": "Example content",
  "severity": "normal",
  "expires": {
    "kind": "none",
    "date": "2026-10-20",
    "afterVisits": 1
  },
  "sharedWithCustomer": true,
  "flaggedNegative": true,
  "authorName": "Example authorName",
  "writtenBy": "crew",
  "createdAt": "2026-10-16T17:04:12.381Z",
  "updatedAt": "2026-10-16T17:04:12.381Z"
}
```

## Endpoints

| Endpoint                             | What it does                           |
| ------------------------------------ | -------------------------------------- |
| `GET /v1/customers/{id}/notes`       | List a customer's notes                |
| `POST /v1/customers/{id}/notes`      | Add a note to a customer               |
| `PUT /v1/customers/{id}/pinned-note` | Set a customer's pinned note           |
| `GET /v1/jobs/{id}/notes`            | List a job's notes                     |
| `POST /v1/jobs/{id}/notes`           | Add an instruction to crews on a job   |
| `GET /v1/notes/{id}`                 | Get a note                             |
| `PATCH /v1/notes/{id}`               | Update a note                          |
| `GET /v1/visits/{id}/notes`          | List a visit's notes                   |
| `POST /v1/visits/{id}/notes`         | Add an instruction to crews on a visit |

## Deleted note

The answer of `DELETE /v1/notes/{id}`.

| Field     | Type                                        | Description               |
| --------- | ------------------------------------------- | ------------------------- |
| `id`      | id                                          | The removed note's id.    |
| `object`  | `"note"`                                    | Always `note`.            |
| `kind`    | `pinned`, `profile`, `operational`, `visit` | What kind of note it was. |
| `deleted` | `true`                                      | Always true.              |

```json
{
  "id": "e4fdac7d-e147-47c4-8d92-230bd9dc5e52",
  "object": "note",
  "kind": "pinned",
  "deleted": true
}
```
