> 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/notes.md).

# Notes

Notes on customers, leads, jobs, and visits.

A customer's pinned note, the notes added to their profile, and the operational notes crews see on jobs and visits, with severity and expiry.

Fields: [The note object](https://docs.shortcutco.com/developers/reference/objects/note).

## List a customer's notes

> The customer's pinned note first (on the first page), then every other note about them newest first: notes on the profile, notes from when they were a lead, the operational notes crews see on their jobs and visits, and the notes written on their visits (\`kind\` \`visit\`, such as a crew member's note from the crew app). Filter by \`kind\`, or by \`propertyId\` for only the notes on that property's jobs and visits.\
> \
> Returns a list of \[note objects]\(<https://docs.shortcutco.com/developers/reference/objects/note>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Notes","description":"A customer's pinned note, the notes added to their profile, and the operational notes crews see on jobs and visits, with severity and expiry.\n\nFields: [The note object](https://docs.shortcutco.com/developers/reference/objects/note)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["customers:read","notes:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"Note":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The note's id."},"object":{"type":"string","const":"note","description":"Always `note`."},"kind":{"type":"string","enum":["pinned","profile","operational","visit"],"description":"`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":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The customer the note is about."},"leadId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The lead the note was written on, for notes from before the lead became a customer."},"jobId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The job an operational note is on."},"visitId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The visit an operational or visit note is on."},"content":{"type":"string","description":"The note's text."},"severity":{"anyOf":[{"type":"string","enum":["normal","warning","critical"]},{"type":"null"}],"description":"How an operational note is shown to crews."},"expires":{"anyOf":[{"$ref":"#/components/schemas/NoteExpiry"},{"type":"null"}],"description":"For operational notes: when the note stops showing."},"sharedWithCustomer":{"type":"boolean","description":"Whether the customer can see it (on their invoice or portal)."},"flaggedNegative":{"type":"boolean","description":"Whether it marks a bad interaction, which counts toward the customer being at risk."},"authorName":{"type":["string","null"],"description":"Who wrote it, or last changed the pinned note."},"writtenBy":{"type":"string","enum":["crew","office"],"description":"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":{"type":"string","format":"date-time","description":"When it was written, ISO 8601 in UTC."},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed, ISO 8601 in UTC."}},"required":["id","object","kind","customerId","leadId","jobId","visitId","content","severity","expires","sharedWithCustomer","flaggedNegative","authorName","writtenBy","createdAt","updatedAt"],"additionalProperties":false,"description":"A note on a customer, lead, job, or visit."},"NoteExpiry":{"type":"object","properties":{"kind":{"type":"string","enum":["none","after_visit","after_visits","date"],"description":"When the note stops showing to crews."},"date":{"type":["string","null"],"description":"For `date`: the last day it shows, `YYYY-MM-DD`."},"afterVisits":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"For `after_visits`: how many visits it shows on."}},"required":["kind","date","afterVisits"],"additionalProperties":false,"description":"When an operational note stops showing to crews."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/customers/{id}/notes":{"get":{"operationId":"customers.notes.list","tags":["Notes"],"summary":"List a customer's notes","description":"The customer's pinned note first (on the first page), then every other note about them newest first: notes on the profile, notes from when they were a lead, the operational notes crews see on their jobs and visits, and the notes written on their visits (`kind` `visit`, such as a crew member's note from the crew app). Filter by `kind`, or by `propertyId` for only the notes on that property's jobs and visits.\n\nReturns a list of [note objects](https://docs.shortcutco.com/developers/reference/objects/note).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"description":"How many items to return, 1-200. Defaults to 50.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The `meta.nextCursor` from the previous page. Omit it for the first page.","schema":{"type":"string","minLength":1,"maxLength":4096}},{"name":"kind","in":"query","required":false,"description":"Only notes of this kind.","schema":{"type":"string","enum":["pinned","profile","operational","visit"]}},{"name":"propertyId","in":"query","required":false,"description":"Only the notes on this property's jobs and visits. Leaves out the pinned note and the notes on the profile, which belong to no property.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Note"}},"meta":{"type":"object","properties":{"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"hasMore":{"type":"boolean","description":"Whether another page exists."}},"required":["nextCursor","hasMore"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Add a note to a customer

> Adds a note to the customer's profile, in the name of the admin the token or app acts for, and it shows on their timeline. For notes crews should see on a job or visit, use \`POST /v1/jobs/{id}/notes\` or \`POST /v1/visits/{id}/notes\`. Send an \`Idempotency-Key\` to retry safely.\
> \
> Returns \[the note object]\(<https://docs.shortcutco.com/developers/reference/objects/note>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Notes","description":"A customer's pinned note, the notes added to their profile, and the operational notes crews see on jobs and visits, with severity and expiry.\n\nFields: [The note object](https://docs.shortcutco.com/developers/reference/objects/note)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["customers:read","notes:write"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Any string up to 255 characters. Retrying with the same key returns the first response instead of repeating the write, for 24 hours.","schema":{"type":"string","maxLength":255}}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"Note":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The note's id."},"object":{"type":"string","const":"note","description":"Always `note`."},"kind":{"type":"string","enum":["pinned","profile","operational","visit"],"description":"`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":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The customer the note is about."},"leadId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The lead the note was written on, for notes from before the lead became a customer."},"jobId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The job an operational note is on."},"visitId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The visit an operational or visit note is on."},"content":{"type":"string","description":"The note's text."},"severity":{"anyOf":[{"type":"string","enum":["normal","warning","critical"]},{"type":"null"}],"description":"How an operational note is shown to crews."},"expires":{"anyOf":[{"$ref":"#/components/schemas/NoteExpiry"},{"type":"null"}],"description":"For operational notes: when the note stops showing."},"sharedWithCustomer":{"type":"boolean","description":"Whether the customer can see it (on their invoice or portal)."},"flaggedNegative":{"type":"boolean","description":"Whether it marks a bad interaction, which counts toward the customer being at risk."},"authorName":{"type":["string","null"],"description":"Who wrote it, or last changed the pinned note."},"writtenBy":{"type":"string","enum":["crew","office"],"description":"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":{"type":"string","format":"date-time","description":"When it was written, ISO 8601 in UTC."},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed, ISO 8601 in UTC."}},"required":["id","object","kind","customerId","leadId","jobId","visitId","content","severity","expires","sharedWithCustomer","flaggedNegative","authorName","writtenBy","createdAt","updatedAt"],"additionalProperties":false,"description":"A note on a customer, lead, job, or visit."},"NoteExpiry":{"type":"object","properties":{"kind":{"type":"string","enum":["none","after_visit","after_visits","date"],"description":"When the note stops showing to crews."},"date":{"type":["string","null"],"description":"For `date`: the last day it shows, `YYYY-MM-DD`."},"afterVisits":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"For `after_visits`: how many visits it shows on."}},"required":["kind","date","afterVisits"],"additionalProperties":false,"description":"When an operational note stops showing to crews."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Conflict with the current state or an in-flight request with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unprocessable":{"description":"The request cannot be applied, or its idempotency key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/customers/{id}/notes":{"post":{"operationId":"customers.notes.create","tags":["Notes"],"summary":"Add a note to a customer","description":"Adds a note to the customer's profile, in the name of the admin the token or app acts for, and it shows on their timeline. For notes crews should see on a job or visit, use `POST /v1/jobs/{id}/notes` or `POST /v1/visits/{id}/notes`. Send an `Idempotency-Key` to retry safely.\n\nReturns [the note object](https://docs.shortcutco.com/developers/reference/objects/note).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","minLength":1,"maxLength":2000,"description":"The note, up to 2000 characters."}},"required":["content"],"additionalProperties":false,"description":"A note on a customer's profile, for staff."}}}},"responses":{"201":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Note"},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Set a customer's pinned note

> Replaces the note pinned at the top of the customer's profile, which staff see first. Null or an empty string clears it; the response is then null. Replacing it overwrites what is there, so read it first (\`GET /v1/customers/{id}/notes?kind=pinned\`) and keep what should stay.\
> \
> Returns \[the note object]\(<https://docs.shortcutco.com/developers/reference/objects/note>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Notes","description":"A customer's pinned note, the notes added to their profile, and the operational notes crews see on jobs and visits, with severity and expiry.\n\nFields: [The note object](https://docs.shortcutco.com/developers/reference/objects/note)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["customers:read","notes:write"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Any string up to 255 characters. Retrying with the same key returns the first response instead of repeating the write, for 24 hours.","schema":{"type":"string","maxLength":255}}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"Note":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The note's id."},"object":{"type":"string","const":"note","description":"Always `note`."},"kind":{"type":"string","enum":["pinned","profile","operational","visit"],"description":"`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":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The customer the note is about."},"leadId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The lead the note was written on, for notes from before the lead became a customer."},"jobId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The job an operational note is on."},"visitId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The visit an operational or visit note is on."},"content":{"type":"string","description":"The note's text."},"severity":{"anyOf":[{"type":"string","enum":["normal","warning","critical"]},{"type":"null"}],"description":"How an operational note is shown to crews."},"expires":{"anyOf":[{"$ref":"#/components/schemas/NoteExpiry"},{"type":"null"}],"description":"For operational notes: when the note stops showing."},"sharedWithCustomer":{"type":"boolean","description":"Whether the customer can see it (on their invoice or portal)."},"flaggedNegative":{"type":"boolean","description":"Whether it marks a bad interaction, which counts toward the customer being at risk."},"authorName":{"type":["string","null"],"description":"Who wrote it, or last changed the pinned note."},"writtenBy":{"type":"string","enum":["crew","office"],"description":"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":{"type":"string","format":"date-time","description":"When it was written, ISO 8601 in UTC."},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed, ISO 8601 in UTC."}},"required":["id","object","kind","customerId","leadId","jobId","visitId","content","severity","expires","sharedWithCustomer","flaggedNegative","authorName","writtenBy","createdAt","updatedAt"],"additionalProperties":false,"description":"A note on a customer, lead, job, or visit."},"NoteExpiry":{"type":"object","properties":{"kind":{"type":"string","enum":["none","after_visit","after_visits","date"],"description":"When the note stops showing to crews."},"date":{"type":["string","null"],"description":"For `date`: the last day it shows, `YYYY-MM-DD`."},"afterVisits":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"For `after_visits`: how many visits it shows on."}},"required":["kind","date","afterVisits"],"additionalProperties":false,"description":"When an operational note stops showing to crews."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Conflict with the current state or an in-flight request with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unprocessable":{"description":"The request cannot be applied, or its idempotency key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/customers/{id}/pinned-note":{"put":{"operationId":"customers.pinned_note.set","tags":["Notes"],"summary":"Set a customer's pinned note","description":"Replaces the note pinned at the top of the customer's profile, which staff see first. Null or an empty string clears it; the response is then null. Replacing it overwrites what is there, so read it first (`GET /v1/customers/{id}/notes?kind=pinned`) and keep what should stay.\n\nReturns [the note object](https://docs.shortcutco.com/developers/reference/objects/note).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"The pinned note at the top of the profile, up to 1,000 characters; null or empty clears it."}},"required":["content"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"$ref":"#/components/schemas/Note"},{"type":"null"}],"description":"A note on a customer, lead, job, or visit."},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## List a job's notes

> The office's every-visit instructions to crews on a job, newest first, including those written on earlier versions of the job (its series). Notes on one visit are read with \`GET /v1/visits/{id}/notes\`. Instructions that have expired are left out unless \`includeExpired\` is true. At most 50 of each; \`meta.hasMore\` says when more were left out.\
> \
> Returns a list of \[note objects]\(<https://docs.shortcutco.com/developers/reference/objects/note>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Notes","description":"A customer's pinned note, the notes added to their profile, and the operational notes crews see on jobs and visits, with severity and expiry.\n\nFields: [The note object](https://docs.shortcutco.com/developers/reference/objects/note)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["jobs:read","notes:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"Note":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The note's id."},"object":{"type":"string","const":"note","description":"Always `note`."},"kind":{"type":"string","enum":["pinned","profile","operational","visit"],"description":"`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":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The customer the note is about."},"leadId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The lead the note was written on, for notes from before the lead became a customer."},"jobId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The job an operational note is on."},"visitId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The visit an operational or visit note is on."},"content":{"type":"string","description":"The note's text."},"severity":{"anyOf":[{"type":"string","enum":["normal","warning","critical"]},{"type":"null"}],"description":"How an operational note is shown to crews."},"expires":{"anyOf":[{"$ref":"#/components/schemas/NoteExpiry"},{"type":"null"}],"description":"For operational notes: when the note stops showing."},"sharedWithCustomer":{"type":"boolean","description":"Whether the customer can see it (on their invoice or portal)."},"flaggedNegative":{"type":"boolean","description":"Whether it marks a bad interaction, which counts toward the customer being at risk."},"authorName":{"type":["string","null"],"description":"Who wrote it, or last changed the pinned note."},"writtenBy":{"type":"string","enum":["crew","office"],"description":"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":{"type":"string","format":"date-time","description":"When it was written, ISO 8601 in UTC."},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed, ISO 8601 in UTC."}},"required":["id","object","kind","customerId","leadId","jobId","visitId","content","severity","expires","sharedWithCustomer","flaggedNegative","authorName","writtenBy","createdAt","updatedAt"],"additionalProperties":false,"description":"A note on a customer, lead, job, or visit."},"NoteExpiry":{"type":"object","properties":{"kind":{"type":"string","enum":["none","after_visit","after_visits","date"],"description":"When the note stops showing to crews."},"date":{"type":["string","null"],"description":"For `date`: the last day it shows, `YYYY-MM-DD`."},"afterVisits":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"For `after_visits`: how many visits it shows on."}},"required":["kind","date","afterVisits"],"additionalProperties":false,"description":"When an operational note stops showing to crews."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/jobs/{id}/notes":{"get":{"operationId":"jobs.notes.list","tags":["Notes"],"summary":"List a job's notes","description":"The office's every-visit instructions to crews on a job, newest first, including those written on earlier versions of the job (its series). Notes on one visit are read with `GET /v1/visits/{id}/notes`. Instructions that have expired are left out unless `includeExpired` is true. At most 50 of each; `meta.hasMore` says when more were left out.\n\nReturns a list of [note objects](https://docs.shortcutco.com/developers/reference/objects/note).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}},{"name":"includeExpired","in":"query","required":false,"description":"`true` also returns the office's instructions to crews that have expired. Omitted or `false`: only the ones that have not expired.","schema":{"anyOf":[{"type":"boolean"},{"type":"string","enum":["true","false"]}]}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Note"}},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Add an instruction to crews on a job

> Adds a note crews see on the job in the crew app, with a severity and, optionally, when it stops showing. Notes for the office belong on the customer (\`POST /v1/customers/{id}/notes\`); gate codes belong on the property (\`PUT /v1/properties/{id}/access\`).\
> \
> Returns \[the note object]\(<https://docs.shortcutco.com/developers/reference/objects/note).\\>
> \
> \*\*Errors specific to this endpoint:\*\* \[\`state\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#state\\_conflict>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Notes","description":"A customer's pinned note, the notes added to their profile, and the operational notes crews see on jobs and visits, with severity and expiry.\n\nFields: [The note object](https://docs.shortcutco.com/developers/reference/objects/note)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["jobs:read","notes:write"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Any string up to 255 characters. Retrying with the same key returns the first response instead of repeating the write, for 24 hours.","schema":{"type":"string","maxLength":255}}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"Note":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The note's id."},"object":{"type":"string","const":"note","description":"Always `note`."},"kind":{"type":"string","enum":["pinned","profile","operational","visit"],"description":"`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":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The customer the note is about."},"leadId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The lead the note was written on, for notes from before the lead became a customer."},"jobId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The job an operational note is on."},"visitId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The visit an operational or visit note is on."},"content":{"type":"string","description":"The note's text."},"severity":{"anyOf":[{"type":"string","enum":["normal","warning","critical"]},{"type":"null"}],"description":"How an operational note is shown to crews."},"expires":{"anyOf":[{"$ref":"#/components/schemas/NoteExpiry"},{"type":"null"}],"description":"For operational notes: when the note stops showing."},"sharedWithCustomer":{"type":"boolean","description":"Whether the customer can see it (on their invoice or portal)."},"flaggedNegative":{"type":"boolean","description":"Whether it marks a bad interaction, which counts toward the customer being at risk."},"authorName":{"type":["string","null"],"description":"Who wrote it, or last changed the pinned note."},"writtenBy":{"type":"string","enum":["crew","office"],"description":"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":{"type":"string","format":"date-time","description":"When it was written, ISO 8601 in UTC."},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed, ISO 8601 in UTC."}},"required":["id","object","kind","customerId","leadId","jobId","visitId","content","severity","expires","sharedWithCustomer","flaggedNegative","authorName","writtenBy","createdAt","updatedAt"],"additionalProperties":false,"description":"A note on a customer, lead, job, or visit."},"NoteExpiry":{"type":"object","properties":{"kind":{"type":"string","enum":["none","after_visit","after_visits","date"],"description":"When the note stops showing to crews."},"date":{"type":["string","null"],"description":"For `date`: the last day it shows, `YYYY-MM-DD`."},"afterVisits":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"For `after_visits`: how many visits it shows on."}},"required":["kind","date","afterVisits"],"additionalProperties":false,"description":"When an operational note stops showing to crews."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Conflict with the current state or an in-flight request with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unprocessable":{"description":"The request cannot be applied, or its idempotency key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/jobs/{id}/notes":{"post":{"operationId":"jobs.notes.create","tags":["Notes"],"summary":"Add an instruction to crews on a job","description":"Adds a note crews see on the job in the crew app, with a severity and, optionally, when it stops showing. Notes for the office belong on the customer (`POST /v1/customers/{id}/notes`); gate codes belong on the property (`PUT /v1/properties/{id}/access`).\n\nReturns [the note object](https://docs.shortcutco.com/developers/reference/objects/note).\n\n**Errors specific to this endpoint:** [`state_conflict`](https://docs.shortcutco.com/developers/concepts/errors#state_conflict). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","minLength":1,"maxLength":2000,"description":"What the crew should know, up to 2000 characters."},"severity":{"type":"string","enum":["normal","warning","critical"],"default":"normal","description":"How the crew app shows it. Defaults to `normal`."},"expires":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"none"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"date"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The last day it shows, `YYYY-MM-DD`."}},"required":["kind","date"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"after_visit"}},"required":["kind"],"additionalProperties":false,"description":"Stops showing after the visit it is on, or for a job note, after the job's next visit."},{"type":"object","properties":{"kind":{"type":"string","const":"after_visits"},"visits":{"type":"integer","minimum":1,"maximum":52,"description":"How many of the job's visits it shows on, starting with the next."}},"required":["kind","visits"],"additionalProperties":false,"description":"Stops showing after this many of the job's visits, starting with the next."}],"description":"When an instruction to crews stops showing. Defaults to never."}},"required":["content"],"additionalProperties":false,"description":"A note crews see on a job or visit."}}}},"responses":{"201":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Note"},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Get a note

> One note on a customer, lead, job, or visit. The pinned note is read with \`GET /v1/customers/{id}/notes?kind=pinned\`.\
> \
> Returns \[the note object]\(<https://docs.shortcutco.com/developers/reference/objects/note>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Notes","description":"A customer's pinned note, the notes added to their profile, and the operational notes crews see on jobs and visits, with severity and expiry.\n\nFields: [The note object](https://docs.shortcutco.com/developers/reference/objects/note)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["notes:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"Note":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The note's id."},"object":{"type":"string","const":"note","description":"Always `note`."},"kind":{"type":"string","enum":["pinned","profile","operational","visit"],"description":"`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":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The customer the note is about."},"leadId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The lead the note was written on, for notes from before the lead became a customer."},"jobId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The job an operational note is on."},"visitId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The visit an operational or visit note is on."},"content":{"type":"string","description":"The note's text."},"severity":{"anyOf":[{"type":"string","enum":["normal","warning","critical"]},{"type":"null"}],"description":"How an operational note is shown to crews."},"expires":{"anyOf":[{"$ref":"#/components/schemas/NoteExpiry"},{"type":"null"}],"description":"For operational notes: when the note stops showing."},"sharedWithCustomer":{"type":"boolean","description":"Whether the customer can see it (on their invoice or portal)."},"flaggedNegative":{"type":"boolean","description":"Whether it marks a bad interaction, which counts toward the customer being at risk."},"authorName":{"type":["string","null"],"description":"Who wrote it, or last changed the pinned note."},"writtenBy":{"type":"string","enum":["crew","office"],"description":"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":{"type":"string","format":"date-time","description":"When it was written, ISO 8601 in UTC."},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed, ISO 8601 in UTC."}},"required":["id","object","kind","customerId","leadId","jobId","visitId","content","severity","expires","sharedWithCustomer","flaggedNegative","authorName","writtenBy","createdAt","updatedAt"],"additionalProperties":false,"description":"A note on a customer, lead, job, or visit."},"NoteExpiry":{"type":"object","properties":{"kind":{"type":"string","enum":["none","after_visit","after_visits","date"],"description":"When the note stops showing to crews."},"date":{"type":["string","null"],"description":"For `date`: the last day it shows, `YYYY-MM-DD`."},"afterVisits":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"For `after_visits`: how many visits it shows on."}},"required":["kind","date","afterVisits"],"additionalProperties":false,"description":"When an operational note stops showing to crews."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/notes/{id}":{"get":{"operationId":"notes.get","tags":["Notes"],"summary":"Get a note","description":"One note on a customer, lead, job, or visit. The pinned note is read with `GET /v1/customers/{id}/notes?kind=pinned`.\n\nReturns [the note object](https://docs.shortcutco.com/developers/reference/objects/note).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Note"},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Remove a note

> Removes a note from the profile, job, or visit, as removing it in the app does: a profile note only by the admin who wrote it, and permanently. A note written on a visit (\`kind\` \`visit\`) can't be removed, as in the crew app (\`422 rule\_violation\`). The pinned note is cleared with \`PUT /v1/customers/{id}/pinned-note\`.\
> \
> Returns \[the note object]\(<https://docs.shortcutco.com/developers/reference/objects/note).\\>
> \
> \*\*Errors specific to this endpoint:\*\* \[\`not\_note\_author\`]\(<https://docs.shortcutco.com/developers/concepts/errors#not\\_note\\_author>), \[\`rule\_violation\`]\(<https://docs.shortcutco.com/developers/concepts/errors#rule\\_violation>), \[\`state\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#state\\_conflict>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Notes","description":"A customer's pinned note, the notes added to their profile, and the operational notes crews see on jobs and visits, with severity and expiry.\n\nFields: [The note object](https://docs.shortcutco.com/developers/reference/objects/note)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["notes:write"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"DeletedNote":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The removed note's id."},"object":{"type":"string","const":"note","description":"Always `note`."},"kind":{"type":"string","enum":["pinned","profile","operational","visit"],"description":"What kind of note it was."},"deleted":{"type":"boolean","const":true,"description":"Always true."}},"required":["id","object","kind","deleted"],"additionalProperties":false},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Conflict with the current state or an in-flight request with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unprocessable":{"description":"The request cannot be applied, or its idempotency key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/notes/{id}":{"delete":{"operationId":"notes.delete","tags":["Notes"],"summary":"Remove a note","description":"Removes a note from the profile, job, or visit, as removing it in the app does: a profile note only by the admin who wrote it, and permanently. A note written on a visit (`kind` `visit`) can't be removed, as in the crew app (`422 rule_violation`). The pinned note is cleared with `PUT /v1/customers/{id}/pinned-note`.\n\nReturns [the note object](https://docs.shortcutco.com/developers/reference/objects/note).\n\n**Errors specific to this endpoint:** [`not_note_author`](https://docs.shortcutco.com/developers/concepts/errors#not_note_author), [`rule_violation`](https://docs.shortcutco.com/developers/concepts/errors#rule_violation), [`state_conflict`](https://docs.shortcutco.com/developers/concepts/errors#state_conflict). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeletedNote"},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Update a note

> Changes a note's text; an instruction to crews on a job or visit (\`kind\` \`operational\`) can also change severity and expiry. A profile note can be changed only by the admin who wrote it (for a token, the admin who created it; for a connected app, the admin who approved it), as in the app. A note written on a visit (\`kind\` \`visit\`) changes only as in the crew app: \`sharedWithCustomer\` puts it on the customer's invoice or takes it off, only for someone on the crew doing the visit and before the visit is finished, and its text never changes. The pinned note is changed with \`PUT /v1/customers/{id}/pinned-note\`.\
> \
> Returns \[the note object]\(<https://docs.shortcutco.com/developers/reference/objects/note).\\>
> \
> \*\*Errors specific to this endpoint:\*\* \[\`not\_note\_author\`]\(<https://docs.shortcutco.com/developers/concepts/errors#not\\_note\\_author>), \[\`rule\_violation\`]\(<https://docs.shortcutco.com/developers/concepts/errors#rule\\_violation>), \[\`state\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#state\\_conflict>), \[\`visit\_notes\_crew\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#visit\\_notes\\_crew\\_only>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Notes","description":"A customer's pinned note, the notes added to their profile, and the operational notes crews see on jobs and visits, with severity and expiry.\n\nFields: [The note object](https://docs.shortcutco.com/developers/reference/objects/note)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["notes:write"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"Note":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The note's id."},"object":{"type":"string","const":"note","description":"Always `note`."},"kind":{"type":"string","enum":["pinned","profile","operational","visit"],"description":"`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":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The customer the note is about."},"leadId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The lead the note was written on, for notes from before the lead became a customer."},"jobId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The job an operational note is on."},"visitId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The visit an operational or visit note is on."},"content":{"type":"string","description":"The note's text."},"severity":{"anyOf":[{"type":"string","enum":["normal","warning","critical"]},{"type":"null"}],"description":"How an operational note is shown to crews."},"expires":{"anyOf":[{"$ref":"#/components/schemas/NoteExpiry"},{"type":"null"}],"description":"For operational notes: when the note stops showing."},"sharedWithCustomer":{"type":"boolean","description":"Whether the customer can see it (on their invoice or portal)."},"flaggedNegative":{"type":"boolean","description":"Whether it marks a bad interaction, which counts toward the customer being at risk."},"authorName":{"type":["string","null"],"description":"Who wrote it, or last changed the pinned note."},"writtenBy":{"type":"string","enum":["crew","office"],"description":"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":{"type":"string","format":"date-time","description":"When it was written, ISO 8601 in UTC."},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed, ISO 8601 in UTC."}},"required":["id","object","kind","customerId","leadId","jobId","visitId","content","severity","expires","sharedWithCustomer","flaggedNegative","authorName","writtenBy","createdAt","updatedAt"],"additionalProperties":false,"description":"A note on a customer, lead, job, or visit."},"NoteExpiry":{"type":"object","properties":{"kind":{"type":"string","enum":["none","after_visit","after_visits","date"],"description":"When the note stops showing to crews."},"date":{"type":["string","null"],"description":"For `date`: the last day it shows, `YYYY-MM-DD`."},"afterVisits":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"For `after_visits`: how many visits it shows on."}},"required":["kind","date","afterVisits"],"additionalProperties":false,"description":"When an operational note stops showing to crews."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Conflict with the current state or an in-flight request with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unprocessable":{"description":"The request cannot be applied, or its idempotency key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/notes/{id}":{"patch":{"operationId":"notes.update","tags":["Notes"],"summary":"Update a note","description":"Changes a note's text; an instruction to crews on a job or visit (`kind` `operational`) can also change severity and expiry. A profile note can be changed only by the admin who wrote it (for a token, the admin who created it; for a connected app, the admin who approved it), as in the app. A note written on a visit (`kind` `visit`) changes only as in the crew app: `sharedWithCustomer` puts it on the customer's invoice or takes it off, only for someone on the crew doing the visit and before the visit is finished, and its text never changes. The pinned note is changed with `PUT /v1/customers/{id}/pinned-note`.\n\nReturns [the note object](https://docs.shortcutco.com/developers/reference/objects/note).\n\n**Errors specific to this endpoint:** [`not_note_author`](https://docs.shortcutco.com/developers/concepts/errors#not_note_author), [`rule_violation`](https://docs.shortcutco.com/developers/concepts/errors#rule_violation), [`state_conflict`](https://docs.shortcutco.com/developers/concepts/errors#state_conflict), [`visit_notes_crew_only`](https://docs.shortcutco.com/developers/concepts/errors#visit_notes_crew_only). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","minLength":1,"maxLength":2000,"description":"The note's new text."},"severity":{"type":"string","enum":["normal","warning","critical"],"description":"Operational notes: how crews see it."},"expires":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"none"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"date"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The last day it shows, `YYYY-MM-DD`."}},"required":["kind","date"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"after_visit"}},"required":["kind"],"additionalProperties":false,"description":"Stops showing after the visit it is on, or for a job note, after the job's next visit."},{"type":"object","properties":{"kind":{"type":"string","const":"after_visits"},"visits":{"type":"integer","minimum":1,"maximum":52,"description":"How many of the job's visits it shows on, starting with the next."}},"required":["kind","visits"],"additionalProperties":false,"description":"Stops showing after this many of the job's visits, starting with the next."}],"description":"When an instruction to crews stops showing. Defaults to never."},"sharedWithCustomer":{"type":"boolean","description":"Visit notes only (`kind` `visit`), and the only thing about one that changes: `true` puts the note on the customer's invoice, `false` takes it off, as the crew app's switch does. Only someone on the crew doing the visit can, before the visit is finished."}},"additionalProperties":false,"description":"The fields to change; send at least one."}}}},"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Note"},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## List a visit's notes

> The notes on a visit, newest first: what was written on the visit (in the crew app, or by the office on the visit) and the office's instructions to crews that apply to it, its own and its job's every-visit ones. \`writtenBy\` says whether a crew member or the office wrote each one. Instructions that have expired are left out unless \`includeExpired\` is true. At most 50 notes written on the visit and 50 instructions of each kind; \`meta.hasMore\` says when more were left out.\
> \
> Returns a list of \[note objects]\(<https://docs.shortcutco.com/developers/reference/objects/note).\\>
> \
> \*\*Errors specific to this endpoint:\*\* \[\`visit\_note\_history\_forbidden\`]\(<https://docs.shortcutco.com/developers/concepts/errors#visit\\_note\\_history\\_forbidden>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Notes","description":"A customer's pinned note, the notes added to their profile, and the operational notes crews see on jobs and visits, with severity and expiry.\n\nFields: [The note object](https://docs.shortcutco.com/developers/reference/objects/note)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["visits:read","notes:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"Note":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The note's id."},"object":{"type":"string","const":"note","description":"Always `note`."},"kind":{"type":"string","enum":["pinned","profile","operational","visit"],"description":"`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":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The customer the note is about."},"leadId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The lead the note was written on, for notes from before the lead became a customer."},"jobId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The job an operational note is on."},"visitId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The visit an operational or visit note is on."},"content":{"type":"string","description":"The note's text."},"severity":{"anyOf":[{"type":"string","enum":["normal","warning","critical"]},{"type":"null"}],"description":"How an operational note is shown to crews."},"expires":{"anyOf":[{"$ref":"#/components/schemas/NoteExpiry"},{"type":"null"}],"description":"For operational notes: when the note stops showing."},"sharedWithCustomer":{"type":"boolean","description":"Whether the customer can see it (on their invoice or portal)."},"flaggedNegative":{"type":"boolean","description":"Whether it marks a bad interaction, which counts toward the customer being at risk."},"authorName":{"type":["string","null"],"description":"Who wrote it, or last changed the pinned note."},"writtenBy":{"type":"string","enum":["crew","office"],"description":"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":{"type":"string","format":"date-time","description":"When it was written, ISO 8601 in UTC."},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed, ISO 8601 in UTC."}},"required":["id","object","kind","customerId","leadId","jobId","visitId","content","severity","expires","sharedWithCustomer","flaggedNegative","authorName","writtenBy","createdAt","updatedAt"],"additionalProperties":false,"description":"A note on a customer, lead, job, or visit."},"NoteExpiry":{"type":"object","properties":{"kind":{"type":"string","enum":["none","after_visit","after_visits","date"],"description":"When the note stops showing to crews."},"date":{"type":["string","null"],"description":"For `date`: the last day it shows, `YYYY-MM-DD`."},"afterVisits":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"For `after_visits`: how many visits it shows on."}},"required":["kind","date","afterVisits"],"additionalProperties":false,"description":"When an operational note stops showing to crews."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/visits/{id}/notes":{"get":{"operationId":"visits.notes.list","tags":["Notes"],"summary":"List a visit's notes","description":"The notes on a visit, newest first: what was written on the visit (in the crew app, or by the office on the visit) and the office's instructions to crews that apply to it, its own and its job's every-visit ones. `writtenBy` says whether a crew member or the office wrote each one. Instructions that have expired are left out unless `includeExpired` is true. At most 50 notes written on the visit and 50 instructions of each kind; `meta.hasMore` says when more were left out.\n\nReturns a list of [note objects](https://docs.shortcutco.com/developers/reference/objects/note).\n\n**Errors specific to this endpoint:** [`visit_note_history_forbidden`](https://docs.shortcutco.com/developers/concepts/errors#visit_note_history_forbidden). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}},{"name":"includeExpired","in":"query","required":false,"description":"`true` also returns the office's instructions to crews that have expired. Omitted or `false`: only the ones that have not expired.","schema":{"anyOf":[{"type":"boolean"},{"type":"string","enum":["true","false"]}]}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Note"}},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Add an instruction to crews on a visit

> Adds a note crews see on the visit in the crew app, with a severity and, optionally, when it stops showing. Notes for the office belong on the customer (\`POST /v1/customers/{id}/notes\`); gate codes belong on the property (\`PUT /v1/properties/{id}/access\`).\
> \
> Returns \[the note object]\(<https://docs.shortcutco.com/developers/reference/objects/note).\\>
> \
> \*\*Errors specific to this endpoint:\*\* \[\`state\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#state\\_conflict>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Notes","description":"A customer's pinned note, the notes added to their profile, and the operational notes crews see on jobs and visits, with severity and expiry.\n\nFields: [The note object](https://docs.shortcutco.com/developers/reference/objects/note)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["visits:read","notes:write"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Any string up to 255 characters. Retrying with the same key returns the first response instead of repeating the write, for 24 hours.","schema":{"type":"string","maxLength":255}}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"Note":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The note's id."},"object":{"type":"string","const":"note","description":"Always `note`."},"kind":{"type":"string","enum":["pinned","profile","operational","visit"],"description":"`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":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The customer the note is about."},"leadId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The lead the note was written on, for notes from before the lead became a customer."},"jobId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The job an operational note is on."},"visitId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The visit an operational or visit note is on."},"content":{"type":"string","description":"The note's text."},"severity":{"anyOf":[{"type":"string","enum":["normal","warning","critical"]},{"type":"null"}],"description":"How an operational note is shown to crews."},"expires":{"anyOf":[{"$ref":"#/components/schemas/NoteExpiry"},{"type":"null"}],"description":"For operational notes: when the note stops showing."},"sharedWithCustomer":{"type":"boolean","description":"Whether the customer can see it (on their invoice or portal)."},"flaggedNegative":{"type":"boolean","description":"Whether it marks a bad interaction, which counts toward the customer being at risk."},"authorName":{"type":["string","null"],"description":"Who wrote it, or last changed the pinned note."},"writtenBy":{"type":"string","enum":["crew","office"],"description":"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":{"type":"string","format":"date-time","description":"When it was written, ISO 8601 in UTC."},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed, ISO 8601 in UTC."}},"required":["id","object","kind","customerId","leadId","jobId","visitId","content","severity","expires","sharedWithCustomer","flaggedNegative","authorName","writtenBy","createdAt","updatedAt"],"additionalProperties":false,"description":"A note on a customer, lead, job, or visit."},"NoteExpiry":{"type":"object","properties":{"kind":{"type":"string","enum":["none","after_visit","after_visits","date"],"description":"When the note stops showing to crews."},"date":{"type":["string","null"],"description":"For `date`: the last day it shows, `YYYY-MM-DD`."},"afterVisits":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"For `after_visits`: how many visits it shows on."}},"required":["kind","date","afterVisits"],"additionalProperties":false,"description":"When an operational note stops showing to crews."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Conflict with the current state or an in-flight request with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unprocessable":{"description":"The request cannot be applied, or its idempotency key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/visits/{id}/notes":{"post":{"operationId":"visits.notes.create","tags":["Notes"],"summary":"Add an instruction to crews on a visit","description":"Adds a note crews see on the visit in the crew app, with a severity and, optionally, when it stops showing. Notes for the office belong on the customer (`POST /v1/customers/{id}/notes`); gate codes belong on the property (`PUT /v1/properties/{id}/access`).\n\nReturns [the note object](https://docs.shortcutco.com/developers/reference/objects/note).\n\n**Errors specific to this endpoint:** [`state_conflict`](https://docs.shortcutco.com/developers/concepts/errors#state_conflict). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","minLength":1,"maxLength":2000,"description":"What the crew should know, up to 2000 characters."},"severity":{"type":"string","enum":["normal","warning","critical"],"default":"normal","description":"How the crew app shows it. Defaults to `normal`."},"expires":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"none"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"date"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The last day it shows, `YYYY-MM-DD`."}},"required":["kind","date"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"after_visit"}},"required":["kind"],"additionalProperties":false,"description":"Stops showing after the visit it is on, or for a job note, after the job's next visit."},{"type":"object","properties":{"kind":{"type":"string","const":"after_visits"},"visits":{"type":"integer","minimum":1,"maximum":52,"description":"How many of the job's visits it shows on, starting with the next."}},"required":["kind","visits"],"additionalProperties":false,"description":"Stops showing after this many of the job's visits, starting with the next."}],"description":"When an instruction to crews stops showing. Defaults to never."}},"required":["content"],"additionalProperties":false,"description":"A note crews see on a job or visit."}}}},"responses":{"201":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Note"},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```
