> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tied.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List notifications

> The calling user's notification feed for this account, 15 to a page, newest activity first.

By default this returns only notifications that are **unread and not snoozed** — pass `includes[]=read` and `includes[]=snoozed` to widen it. That also changes what `unread_count` means: without `read`, every result is unread and `unread_count` equals `count`; with it, `unread_count` is the unread subset.

The envelope is nested one level deeper than the rest of the API: `payload` and `meta` live under `data`.



## OpenAPI

````yaml /api-reference/openapi.json get /api/v1/accounts/{account_id}/notifications
openapi: 3.0.4
info:
  title: Tied API
  description: >-
    The Tied REST API. Three families of endpoint, each with its own credential:
    **Application** for everything inside an account, **Platform** for
    provisioning accounts and users, and **Client** for acting as a contact from
    your own surface.
  version: 1.1.0
  termsOfService: https://tied.com/legal
  contact:
    email: hello@tied.com
  license:
    name: MIT License
    url: https://opensource.org/licenses/MIT
servers:
  - url: https://app.tied.com
    description: Tied cloud
security: []
tags:
  - name: Account AgentBots
    description: Account-specific Agent Bots
  - name: Agents
    description: Agent management APIs
  - name: Canned Responses
    description: Pre-defined responses for common queries
  - name: Contacts
    description: Contact management APIs
  - name: Contact Labels
    description: Manage contact labels
  - name: Conversation Assignments
    description: Manage conversation assignments
  - name: Conversation Labels
    description: Manage conversation labels
  - name: Conversations
    description: Conversation management APIs
  - name: Custom Attributes
    description: Custom fields for contacts and conversations
  - name: Custom Filters
    description: Saved filters for conversations
  - name: Inboxes
    description: Communication channels setup
  - name: Integrations
    description: Third-party integrations
  - name: Messages
    description: Message management APIs
  - name: Profile
    description: User profile APIs
  - name: Reports
    description: Analytics and reporting APIs
  - name: Teams
    description: Team management APIs
  - name: Webhooks
    description: Event notification webhooks
  - name: Automation Rule
    description: Workflow automation rules
  - name: Help Center
    description: Knowledge base management
  - name: Contacts API
    description: Public contact APIs
  - name: Conversations API
    description: Public conversation APIs
  - name: Messages API
    description: Public message APIs
  - name: CSAT Survey Page
    description: Customer satisfaction survey
  - name: Account
    description: >-
      The authenticated user's own account — read and update account settings.
      Distinct from the Platform family's **Accounts**, which provisions
      accounts across an installation.
  - name: Audit Logs
    description: Read the account's audit trail
  - name: Inbox API
    description: Public inbox lookup by channel identifier
  - name: Labels
    description: >-
      Create and manage the account's labels. Applying one to a conversation or
      contact is a separate endpoint under those resources.
  - name: Macros
    description: >-
      Saved multi-step actions an agent — or an integration — can run against
      one or more conversations.
  - name: Campaigns
    description: Ongoing website campaigns and one-off SMS and WhatsApp sends.
  - name: Contact Notes
    description: Internal notes on a contact. Never visible to the contact.
  - name: Help Center Categories
    description: Categories group a portal's articles, one tree per allowed locale.
  - name: Help Center Articles
    description: The articles a portal publishes, and their draft and archived states.
  - name: Summary Reports
    description: Per-agent, per-team, per-inbox and per-label totals for a period, as JSON.
  - name: Live Reports
    description: Right-now queue counts. No date range — these describe the present.
  - name: CSAT
    description: >-
      The satisfaction ratings contacts have submitted, and the metrics computed
      from them.
  - name: Notifications
    description: >-
      The per-user notification feed, its read and snooze state, and the
      settings that decide what lands in it.
  - name: Conversation Participants
    description: >-
      The agents watching a conversation. Participants get notified about it
      without being assigned to it.
  - name: Draft Messages
    description: >-
      The unsent reply held for a conversation. Stored in Redis, one per
      conversation.
  - name: Search
    description: >-
      One search service across conversations, contacts, messages and Help
      Center articles.
  - name: Dashboard Apps
    description: Embedded pages that appear as a tab beside a conversation.
  - name: Assignment Policies
    description: How conversations are handed out, and which inbox uses which policy.
  - name: Files
    description: Storing a file so another endpoint can attach it.
  - name: Bot Flows
    description: >-
      Scripted conversation flows, their versions, and the publish and rollback
      that move between them.
  - name: Billing
    description: >-
      Credit balance, usage, invoices, spend controls and the provider-hosted
      payment flows.
  - name: AMB Templates
    description: >-
      Saved Apple Messages primitive payloads an agent can reuse from the
      composer.
  - name: AMB Onboarding
    description: The in-flight Apple Messages for Business registration for an account.
  - name: Widget Session
    description: Starting a widget session and reading the visitor it belongs to.
  - name: Widget Conversation
    description: The visitor's conversation and its messages.
  - name: Widget Context
    description: Campaigns, agents, labels, events and uploads for a widget session.
  - name: CSAT Survey
    description: The public, unauthenticated survey a contact answers from a link.
  - name: Workspace
    description: Scheduling and cancelling deletion of the whole workspace.
paths:
  /api/v1/accounts/{account_id}/notifications:
    parameters:
      - $ref: '#/components/parameters/account_id'
    get:
      tags:
        - Notifications
      summary: List notifications
      description: >-
        The calling user's notification feed for this account, 15 to a page,
        newest activity first.


        By default this returns only notifications that are **unread and not
        snoozed** — pass `includes[]=read` and `includes[]=snoozed` to widen it.
        That also changes what `unread_count` means: without `read`, every
        result is unread and `unread_count` equals `count`; with it,
        `unread_count` is the unread subset.


        The envelope is nested one level deeper than the rest of the API:
        `payload` and `meta` live under `data`.
      operationId: list-notifications
      parameters:
        - name: includes
          in: query
          required: false
          description: >-
            Widen the feed. Repeat the parameter as
            `includes[]=read&includes[]=snoozed`.
          schema:
            type: string
            enum:
              - read
              - snoozed
        - name: since
          in: query
          required: false
          description: >-
            Only notifications with `last_activity_at` at or after this Unix
            epoch time.
          schema:
            type: string
        - name: until
          in: query
          required: false
          description: >-
            Only notifications with `last_activity_at` at or before this Unix
            epoch time.
          schema:
            type: string
        - name: sort_order
          in: query
          required: false
          description: Order by `last_activity_at`. Defaults to `desc`.
          schema:
            type: string
            enum:
              - asc
              - desc
        - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/notification_list_response'
              example:
                data:
                  meta:
                    unread_count: 2
                    count: 2
                    current_page: 1
                  payload:
                    - id: 1
                      notification_type: conversation_assignment
                      push_message_title: A conversation (#190) has been assigned to you
                      push_message_body: 'Jen Park: Need help choosing between two plans.'
                      primary_actor_type: Conversation
                      primary_actor_id: 190
                      primary_actor:
                        additional_attributes: {}
                        can_reply: true
                        channel: Channel::WebWidget
                        contact_inbox:
                          id: 159
                          contact_id: 163
                          inbox_id: 4
                          source_id: EXAMPLE_SOURCE_ID
                          created_at: '2026-09-21T03:17:03.949Z'
                          updated_at: '2026-09-21T03:17:03.949Z'
                          hmac_verified: false
                          pubsub_token: EXAMPLE_PUBSUB_TOKEN
                        id: 190
                        inbox_id: 4
                        messages:
                          - id: 639
                            content: Need help choosing between two plans.
                            account_id: 1
                            inbox_id: 4
                            conversation_id: 190
                            message_type: 0
                            created_at: 1789948863
                            updated_at: '2026-09-21T00:01:03.954Z'
                            private: false
                            status: sent
                            source_id: null
                            content_type: text
                            content_attributes: {}
                            sender_type: Contact
                            sender_id: 163
                            external_source_ids: {}
                            additional_attributes: {}
                            processed_message_content: null
                            sentiment: {}
                            source_identity_uniqueness_exempt_at: null
                            actor: null
                            conversation:
                              assignee_id: null
                              unread_count: 0
                              last_activity_at: 1789948623
                              contact_inbox:
                                source_id: EXAMPLE_SOURCE_ID
                            sender:
                              additional_attributes: {}
                              custom_attributes: {}
                              email: null
                              id: 163
                              identifier: null
                              name: Jen Park
                              phone_number: null
                              thumbnail: ''
                              thumbnail_background_color: null
                              domain_logo_avatar: false
                              customer_verified: false
                              blocked: false
                              type: contact
                        labels: []
                        meta:
                          sender:
                            additional_attributes: {}
                            custom_attributes: {}
                            email: null
                            id: 163
                            identifier: null
                            name: Jen Park
                            phone_number: null
                            thumbnail: ''
                            thumbnail_background_color: null
                            domain_logo_avatar: false
                            customer_verified: false
                            blocked: false
                            type: contact
                          assignee: null
                          team: null
                          hmac_verified: false
                        status: open
                        custom_attributes: {}
                        snoozed_until: null
                        unread_count: 0
                        first_reply_created_at: null
                        priority: null
                        waiting_since: 0
                        agent_last_seen_at: 1789948923
                        contact_last_seen_at: 0
                        last_activity_at: 1789948623
                        timestamp: 1789948623
                        created_at: 1789960623
                        updated_at: 1789960624.0422678
                      read_at: null
                      secondary_actor: null
                      user:
                        id: 1
                        name: Alex Rivera
                        available_name: Alex Rivera
                        avatar_url: ''
                        type: user
                        availability_status: offline
                        thumbnail: /dashboard/images/default-contact-avatars/031.svg
                        illustration_avatar: true
                        accent_color: null
                      created_at: 1789960145
                      last_activity_at: 1789960145
                      snoozed_until: null
                      meta: {}
                    - id: 2
                      notification_type: assigned_conversation_new_message
                      push_message_title: A new message is created in conversation (#189)
                      push_message_body: ': No content'
                      primary_actor_type: Conversation
                      primary_actor_id: 189
                      primary_actor:
                        additional_attributes: {}
                        can_reply: true
                        channel: Channel::WebWidget
                        contact_inbox:
                          id: 158
                          contact_id: 162
                          inbox_id: 4
                          source_id: EXAMPLE_SOURCE_ID
                          created_at: '2026-09-21T03:17:03.935Z'
                          updated_at: '2026-09-21T03:17:03.935Z'
                          hmac_verified: false
                          pubsub_token: EXAMPLE_PUBSUB_TOKEN
                        id: 189
                        inbox_id: 4
                        messages:
                          - id: 636
                            content: Reading your docs right now.
                            account_id: 1
                            inbox_id: 4
                            conversation_id: 189
                            message_type: 0
                            created_at: 1789950063
                            updated_at: '2026-09-21T00:21:03.943Z'
                            private: false
                            status: sent
                            source_id: null
                            content_type: text
                            content_attributes: {}
                            sender_type: Contact
                            sender_id: 162
                            external_source_ids: {}
                            additional_attributes: {}
                            processed_message_content: null
                            sentiment: {}
                            source_identity_uniqueness_exempt_at: null
                            actor: null
                            conversation:
                              assignee_id: null
                              unread_count: 0
                              last_activity_at: 1789949823
                              contact_inbox:
                                source_id: EXAMPLE_SOURCE_ID
                            sender:
                              additional_attributes: {}
                              custom_attributes: {}
                              email: null
                              id: 162
                              identifier: null
                              name: Alex Rivera
                              phone_number: null
                              thumbnail: ''
                              thumbnail_background_color: null
                              domain_logo_avatar: false
                              customer_verified: false
                              blocked: false
                              type: contact
                        labels: []
                        meta:
                          sender:
                            additional_attributes: {}
                            custom_attributes: {}
                            email: null
                            id: 162
                            identifier: null
                            name: Alex Rivera
                            phone_number: null
                            thumbnail: ''
                            thumbnail_background_color: null
                            domain_logo_avatar: false
                            customer_verified: false
                            blocked: false
                            type: contact
                          assignee: null
                          team: null
                          hmac_verified: false
                        status: open
                        custom_attributes: {}
                        snoozed_until: null
                        unread_count: 0
                        first_reply_created_at: null
                        priority: null
                        waiting_since: 0
                        agent_last_seen_at: 1789950123
                        contact_last_seen_at: 0
                        last_activity_at: 1789949823
                        timestamp: 1789949823
                        created_at: 1789960623
                        updated_at: 1789960624.037724
                      read_at: null
                      secondary_actor: null
                      user:
                        id: 1
                        name: Alex Rivera
                        available_name: Alex Rivera
                        avatar_url: ''
                        type: user
                        availability_status: offline
                        thumbnail: /dashboard/images/default-contact-avatars/031.svg
                        illustration_avatar: true
                        accent_color: null
                      created_at: 1789958165
                      last_activity_at: 1789958165
                      snoozed_until: null
                      meta: {}
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
      security:
        - userApiKey: []
components:
  parameters:
    account_id:
      in: path
      name: id
      schema:
        type: integer
      required: true
      description: The numeric ID of the account
    page:
      in: query
      name: page
      schema:
        type: integer
        default: 1
      required: false
      description: The page parameter
  schemas:
    notification_list_response:
      type: object
      description: >-
        The notification feed is nested one level deeper than the rest of the
        API — the payload and meta live under `data`.
      properties:
        data:
          type: object
          properties:
            payload:
              type: array
              items:
                $ref: '#/components/schemas/notification_list_item'
              description: The notifications on this page.
            meta:
              type: object
              properties:
                unread_count:
                  type: integer
                  description: >-
                    Unread notifications. Identical to `count` unless you asked
                    for read ones with `includes[]=read`, in which case this
                    counts only the unread subset.
                count:
                  type: integer
                  description: Total matching the current filters.
                current_page:
                  type: integer
                  description: The page this response represents.
              description: Counts and the current page.
          description: >-
            The feed is nested under `data`, one level deeper than the rest of
            the API.
    error_message:
      type: object
      description: >-
        The shape returned by `render_unauthorized`, `render_not_found_error`
        and `render_could_not_create_error`.
      properties:
        error:
          type: string
          description: A single human-readable message.
          example: Resource could not be found
      required:
        - error
    notification_list_item:
      type: object
      description: >-
        A notification as the feed renders it: the record plus ready-made push
        copy and the whole conversation it refers to.
      properties:
        id:
          type: integer
          description: The numeric ID of the notification.
        account_id:
          type: integer
          description: The account the notification belongs to.
        user_id:
          type: integer
          description: The user the notification is for.
        notification_type:
          type: string
          enum:
            - conversation_creation
            - conversation_assignment
            - assigned_conversation_new_message
            - conversation_mention
            - participating_conversation_new_message
            - sla_missed_first_response
            - sla_missed_next_response
            - sla_missed_resolution
          description: What happened.
        primary_actor_type:
          type: string
          description: >-
            Always `Conversation` today — it is the only primary actor the app
            creates notifications for.
        primary_actor_id:
          type: integer
          description: The conversation the notification is about.
        secondary_actor_type:
          type: string
          nullable: true
          description: >-
            The message that triggered it, where one applies. Null when the
            system acted rather than a person.
        secondary_actor_id:
          type: integer
          nullable: true
          description: ID of the secondary actor.
        read_at:
          type: string
          nullable: true
          description: ISO-8601 timestamp of when it was read. Null while unread.
        snoozed_until:
          type: string
          nullable: true
          description: >-
            ISO-8601 timestamp of when it should reappear. Null when not
            snoozed.
        last_activity_at:
          type: string
          description: >-
            ISO-8601 timestamp the feed is sorted by — it moves when a new
            message arrives on the same conversation.
        meta:
          type: object
          description: Internal bookkeeping, including `last_snoozed_at`.
        created_at:
          type: string
          description: ISO-8601 timestamp of creation.
        updated_at:
          type: string
          description: ISO-8601 timestamp of the last change.
        push_message_title:
          type: string
          description: Ready-made title for a push or email notification.
        push_message_body:
          type: string
          description: >-
            Ready-made body, usually the sender name and the message that
            triggered it.
        primary_actor:
          $ref: '#/components/schemas/conversation'
    conversation:
      type: object
      properties:
        id:
          type: number
          description: ID of the conversation
        messages:
          type: array
          items:
            $ref: '#/components/schemas/message'
          description: The messages in the thread, oldest first.
        account_id:
          type: number
          description: Account Id
        uuid:
          type: string
          description: UUID of the conversation
        additional_attributes:
          type: object
          description: >-
            The object containing additional attributes related to the
            conversation
        agent_last_seen_at:
          type: number
          description: The last activity at of the agent
        assignee_last_seen_at:
          type: number
          description: The last activity at of the assignee
        can_reply:
          type: boolean
          description: Whether the conversation can be replied to
        contact_last_seen_at:
          type: number
          description: The last activity at of the contact
        custom_attributes:
          type: object
          description: >-
            The object to save custom attributes for conversation, accepts
            custom attributes key and value
        inbox_id:
          type: number
          description: ID of the inbox
        labels:
          type: array
          items:
            type: string
          description: The labels of the conversation
        muted:
          type: boolean
          description: Whether the conversation is muted
        snoozed_until:
          type: number
          description: The time at which the conversation will be unmuted
          nullable: true
        status:
          type: string
          enum:
            - open
            - resolved
            - pending
          description: The status of the conversation
        created_at:
          type: number
          description: The time at which conversation was created
        updated_at:
          type: number
          description: The time at which conversation was updated
        timestamp:
          description: Unix epoch seconds for the conversation's last activity.
          type: integer
          format: int64
        first_reply_created_at:
          type: number
          description: The time at which the first reply was created
        unread_count:
          type: number
          description: The number of unread messages
        last_non_activity_message:
          $ref: '#/components/schemas/message'
        last_activity_at:
          type: number
          description: The last activity at of the conversation
        priority:
          type: string
          description: The priority of the conversation
          nullable: true
        waiting_since:
          type: number
          description: The time at which the conversation was waiting
        sla_policy_id:
          type: number
          description: The ID of the SLA policy
          nullable: true
        applied_sla:
          type: object
          description: The applied SLA
        sla_events:
          type: array
          items:
            type: object
            description: SLA event objects
          description: SLA breaches and warnings recorded against this conversation.
    message:
      type: object
      properties:
        id:
          type: number
          description: The ID of the message
        content:
          type: string
          description: The text content of the message
          nullable: true
        account_id:
          type: number
          description: The ID of the account
        inbox_id:
          type: number
          description: The ID of the inbox
        conversation_id:
          type: number
          description: The ID of the conversation
        message_type:
          description: 0 = incoming, 1 = outgoing, 2 = activity, 3 = template.
          type: integer
          enum:
            - 0
            - 1
            - 2
            - 3
        created_at:
          type: integer
          description: The time at which message was created
        updated_at:
          description: >-
            ISO-8601 timestamp of the last update. Note this differs from
            `created_at` on the same object, which is unix epoch seconds.
          type: string
          format: date-time
          nullable: true
        private:
          type: boolean
          description: The flags which shows whether the message is private or not
        status:
          type: string
          enum:
            - sent
            - delivered
            - read
            - failed
          description: The status of the message
        source_id:
          type: string
          description: The source ID of the message
          nullable: true
        content_type:
          type: string
          enum:
            - text
            - input_select
            - cards
            - form
          description: The type of the template message
        content_attributes:
          type: object
          description: The content attributes for each content_type
        sender_type:
          description: >-
            The class of the sender, capitalised to match the underlying record
            type.
          type: string
          enum:
            - Contact
            - User
            - AgentBot
          nullable: true
        sender_id:
          type: number
          description: The ID of the sender
        external_source_ids:
          type: object
          description: The external source IDs of the message
        additional_attributes:
          type: object
          description: The additional attributes of the message
        processed_message_content:
          type: string
          description: The processed message content
          nullable: true
        sentiment:
          type: object
          description: The sentiment of the message
        conversation:
          type: object
          description: The conversation object
        attachment:
          type: object
          description: The file object attached to the image
        sender:
          type: object
          description: User/Agent/AgentBot object
  securitySchemes:
    userApiKey:
      type: apiKey
      in: header
      name: api_access_token
      description: >-
        This token can be obtained by visiting the profile page or via rails
        console. Provides access to  endpoints based on the user permissions
        levels. This token can be saved by an external system when user is
        created via API, to perform activities on behalf of the user.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.