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

# List notifications for the caller

List the caller's own notifications, newest first — the inbox behind the bell in the service workspace. The inbox is personal: it is read as the caller and never returns anyone else's notifications. Set unreadOnly to read only the ones that have not been read yet. These are notifications to staff, inside Flow. They are not the messages Flow sends out to customers — those are SMS and e-mail, and are read through the notifications endpoints. A notification goes to the user the service order is assigned to. When a service order is not assigned to anyone it goes to the service staff of the store that owns it instead — the users holding a role that grants SERVICE\_ORDER assigned at that store itself, not at its organization and not tenant-wide — so nothing is left waiting on a person who is not looking at it. Nobody is ever notified about their own action. There is no push delivery: poll this endpoint, and the unread count endpoint for the badge, every 30 to 60 seconds.

Required permissions: SERVICE\_ORDER

```json
{"openapi":"3.0.2","info":{"title":"Flow Retail API version 2","version":"2.0.0"},"tags":[{"name":"Service","description":"Service"}],"servers":[{"description":"Flow Retail Production","url":"https://api.flowretail.com/v2"},{"description":"Flow Retail Stage","url":"https://api.stage.flowretail.com/v2"}],"security":[{"accessToken":[]},{"authToken":[]},{"integrationToken":[]}],"components":{"securitySchemes":{"accessToken":{"description":"Access token recevied after user login with a deviceToken","scheme":"bearer","type":"http"},"authToken":{"description":"Token received from the auth service","scheme":"bearer","type":"http"},"integrationToken":{"scheme":"bearer","type":"http"}},"responses":{"ServiceUserNotificationListResponse":{"description":"Example response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ServiceUserNotificationResponseSchema"}},"paging":{"$ref":"#/components/schemas/Paging"}},"required":["items","paging"]}}}}},"schemas":{"ServiceUserNotificationResponseSchema":{"title":"ServiceUserNotificationResponseSchema","description":"One notification in the caller's own inbox — what the bell in the service workspace shows, and what its badge counts while it is unread. A notification is personal: it belongs to the one user it was written for, and every inbox operation serves the caller's own notifications and nobody else's — the caller is the person the request is authenticated as, which on a shared screen is the person whose PIN unlocked it.\nThis is not the notification the customer gets. The notifications endpoints are the log of the SMS and e-mail Flow sends out — the customer messages, and the e-mail that goes to a member of staff when an entry is written with the notify switch set. What is returned here is the other thing: an in-app message to one member of staff, which never leaves Flow. The e-mail that accompanies it is an ordinary send, recorded in that log like any other.\nA notification goes to the user the service order is assigned to. When a service order is not assigned to anyone it goes to the service staff of the store that owns it instead — the users holding a role that grants SERVICE_ORDER assigned at that store itself, not at its organization and not tenant-wide — so nothing is left waiting on a person who is not looking at it. Nobody is ever notified about their own action.\nThere is no push delivery: clients read the list and the unread count by polling, every 30 to 60 seconds.","type":"object","required":["serviceUserNotificationUid","type","serviceOrderUid","serviceEventUid","title","body","readAt","createdAt"],"properties":{"serviceUserNotificationUid":{"$ref":"#/components/schemas/UID"},"type":{"$ref":"#/components/schemas/ServiceUserNotificationTypeENUM"},"serviceOrderUid":{"description":"The service order the notification is about, so it can be opened straight from the bell. An empty string on a notification that is not about one service order.","type":"string","pattern":"^[A-Za-z0-9-_]*"},"serviceEventUid":{"description":"The timeline event the notification came out of, such as the note that was written or the message the customer sent. An empty string when no single event lies behind it, as on the due and overdue reminders a scan of the open service orders writes.","type":"string","pattern":"^[A-Za-z0-9-_]*"},"title":{"type":"string","description":"The one line the notification is shown by in the bell."},"body":{"type":"string","description":"What happened, in a sentence, under the title. An empty string on a notification whose title says all there is to say."},"readAt":{"type":"string","format":"date-time","nullable":true,"description":"When the user read the notification. Null while it is unread — an unread notification is exactly one whose readAt is null, and those are what the badge counts."},"createdAt":{"type":"string","format":"date-time"}}},"UID":{"title":"UID","type":"string","pattern":"^[A-Za-z0-9-_]+"},"ServiceUserNotificationTypeENUM":{"title":"ServiceUserNotificationTypeENUM","description":"What a notification in a user's inbox is about. Every notification has exactly one type.\nASSIGNED_TO_YOU: a service order was handed to the user. NOTE: an entry was written on a service order's timeline with the notify switch set on it, which is the only thing that writes this type — it goes to the user the service order is assigned to, or to the service staff of the store that owns it when nobody is assigned, never to anyone following the case. STATUS_CHANGED: written when somebody else moves a service order that is assigned to the user to another status. PRIORITY_RAISED: written by the service order update when the priority of a service order rises. DUE_TODAY: the day of a service order's readyAtEstimate, in the tenant's timezone, is today. OVERDUE: that day is past and the service order is not finished. Neither is written for a service order that is on a status of the state READY_FOR_PICKUP when the scan reaches it: its work is ready, so nothing is due on it and it is not late. QUOTE_ANSWERED: the customer answered the price they were offered — with the service portal's buttons themselves, or over the counter, on the phone or in writing with staff recording it, which is the same business fact whichever way it reached the store. TERMS_ACCEPTED: reserved for the customer accepting the terms and conditions on a service order, in the service portal, on a counter device or in the store — nothing writes it yet. CUSTOMER_MESSAGE: the customer wrote a message in the service portal. PARTS_RECEIVED: reserved for parts ordered for a service order arriving, so the work that was waiting on them can go on — nothing writes it yet. MOVED_TO_STORE: written when a service order is moved to another store, to the service staff of the receiving store, so the work has arrived at their counter.\nDUE_TODAY and OVERDUE come out of a worker that scans the open service orders rather than out of something someone did. They carry a dedupe key, so a service order is only ever notified once per kind per day however often the worker runs — the inbox never stacks the same reminder twice. A service order due at 14:00 is reminded about as overdue on the next day's scan, while the overdue search filter counts it late from 14:00.","enum":["ASSIGNED_TO_YOU","NOTE","STATUS_CHANGED","PRIORITY_RAISED","DUE_TODAY","OVERDUE","QUOTE_ANSWERED","TERMS_ACCEPTED","CUSTOMER_MESSAGE","PARTS_RECEIVED","MOVED_TO_STORE"],"type":"string"},"Paging":{"description":"totalCount The total number of items in the result set.\n\npageSize The number of items per page.\n\npageNumber The current page in the result set.","properties":{"pageNumber":{"type":"integer"},"pageSize":{"type":"integer"},"totalCount":{"type":"integer"}},"required":["totalCount","pageSize","pageNumber"],"title":"Paging","type":"object"}},"parameters":{"unreadOnlyQuery":{"name":"unreadOnly","in":"query","required":false,"schema":{"type":"boolean"},"description":"Return only the notifications that have not been read yet. Defaults to false."},"pageNumberQuery":{"description":"Reference to a specific page in a result set.","in":"query","name":"pageNumber","required":false,"schema":{"type":"integer"}},"pageSizeQuery":{"description":"The number of items per page in a result set.","in":"query","name":"pageSize","required":false,"schema":{"type":"integer"}}}},"paths":{"/tenants/{tenantUid}/serviceorders/usernotifications":{"get":{"summary":"List notifications for the caller","tags":["Service"],"responses":{"200":{"$ref":"#/components/responses/ServiceUserNotificationListResponse"}},"operationId":"get-serviceorders-usernotifications","description":"List the caller's own notifications, newest first — the inbox behind the bell in the service workspace. The inbox is personal: it is read as the caller and never returns anyone else's notifications. Set unreadOnly to read only the ones that have not been read yet.\nThese are notifications to staff, inside Flow. They are not the messages Flow sends out to customers — those are SMS and e-mail, and are read through the notifications endpoints.\nA notification goes to the user the service order is assigned to. When a service order is not assigned to anyone it goes to the service staff of the store that owns it instead — the users holding a role that grants SERVICE_ORDER assigned at that store itself, not at its organization and not tenant-wide — so nothing is left waiting on a person who is not looking at it. Nobody is ever notified about their own action.\nThere is no push delivery: poll this endpoint, and the unread count endpoint for the badge, every 30 to 60 seconds.\n\nRequired permissions: SERVICE_ORDER","parameters":[{"$ref":"#/components/parameters/unreadOnlyQuery"},{"$ref":"#/components/parameters/pageNumberQuery"},{"$ref":"#/components/parameters/pageSizeQuery"}]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flowretail.com/docs/developers/api-documentation/service/list-notifications-for-the-caller.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
