Extole User Notifications API

openapi: 3.0.1
info:
  description: 'Consumer-to-Extole integration endpoints: consumer event submission, zone rendering, profile management, and SDK-backing operations for browser and native app environments.'
  title: Integration API - Consumer to Extole Audiences User Notifications API
  version: '1.0'
servers:
- description: Production
  url: https://{brand}.extole.io
  variables:
    brand:
      default: yourcompany
      description: Your Extole client subdomain (e.g. 'mycompany' for mycompany.extole.io)
security:
- HEADER: []
- QUERY: []
- COOKIE: []
tags:
- name: User Notifications
paths:
  /v6/notifications:
    get:
      description: Returns the calling user's in-portal notifications sorted newest first. Use the `limit` and `offset` parameters to page through results. Notifications include report completion alerts, campaign status changes, and custom client events fired via `createClientEvent`.
      operationId: listNotifications
      parameters:
      - in: query
        name: limit
        schema:
          format: int32
          type: integer
      - in: query
        name: offset
        schema:
          format: int32
          type: integer
      - in: query
        name: having_all_tags
        schema:
          items:
            type: string
          type: array
          uniqueItems: true
      - in: query
        name: event_id
        schema:
          type: string
      - in: query
        name: subscription_id
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/NotificationResponse'
                type: array
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: List recent notifications
      tags:
      - User Notifications
      x-extole-bundle: management
      x-extole-visibility: visible
  /v6/notifications/read:
    get:
      description: Returns the timestamp up to which the calling user has read their notifications. Use this cursor to determine which notifications are unread (those created after the returned timestamp). Advance the cursor with `updateNotificationCursor`.
      operationId: getNotificationCursor
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationCursorResponse'
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Get notification read cursor
      tags:
      - User Notifications
      x-extole-bundle: management
      x-extole-visibility: visible
    post:
      description: Advances the read cursor to the supplied timestamp, marking all notifications created at or before that time as read for the calling user. Returns the updated cursor state. Use `getNotificationCursor` to retrieve the current cursor position.
      operationId: updateNotificationCursor
      requestBody:
        content:
          application/json:
            example:
              last_read_event_time: '2025-10-24T02:00:00-07:00'
            schema:
              $ref: '#/components/schemas/NotificationCursorRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationCursorResponse'
          description: Updated notification read cursor.
        '400':
          content:
            application/json:
              examples:
                missing_date_time:
                  $ref: '#/components/examples/missing_date_time'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: 'Invalid read-cursor update: `missing_date_time` if no timestamp was supplied in the request body.'
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Mark notifications as read
      tags:
      - User Notifications
      x-extole-bundle: management
      x-extole-visibility: visible
  /v6/notifications/snoozes:
    get:
      description: Returns all active notification snooze rules for the calling portal user, sorted newest first. A snooze rule suppresses notifications matching specified tags until its expiry time. To list snoozes for a different user, use `listSnoozesByUser`.
      operationId: listSnoozes
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/SnoozeResponse'
                type: array
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                invalid_snooze_id:
                  $ref: '#/components/examples/invalid_snooze_id'
                invalid_user_id:
                  $ref: '#/components/examples/invalid_user_id'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
                user_not_found:
                  $ref: '#/components/examples/user_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: List notification snoozes for the caller
      tags:
      - User Notifications
      x-extole-bundle: management
      x-extole-visibility: visible
    post:
      description: Creates a snooze rule that suppresses portal notifications matching the supplied tags for the calling portal user until the `expires_at` timestamp. Returns the newly created snooze with its assigned id. To create a snooze for a different user, use `createSnoozeByUser`.
      operationId: createSnooze
      requestBody:
        content:
          application/json:
            example:
              comment: comment
              expires_at: '2025-10-24T02:00:00-07:00'
              having_exactly_tags:
              - having_exactly_tag
            schema:
              $ref: '#/components/schemas/SnoozeRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SnoozeResponse'
          description: Created notification snooze.
        '400':
          content:
            application/json:
              examples:
                invalid_expires_at:
                  $ref: '#/components/examples/invalid_expires_at'
                missing_tags:
                  $ref: '#/components/examples/missing_tags'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: 'Snooze creation failed: `missing_tags` if no notification tags were supplied; `invalid_expires_at` if the expiry timestamp is not valid.'
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Create a notification snooze for the caller
      tags:
      - User Notifications
      x-extole-bundle: management
      x-extole-visibility: visible
  /v6/notifications/snoozes/{snoozeId}:
    get:
      description: Returns the snooze rule identified by `snoozeId` belonging to the calling portal user. Returns the tags being snoozed and the expiry timestamp. To retrieve a snooze for a different user, use `getSnoozeByUser`.
      operationId: getSnooze
      parameters:
      - in: path
        name: snoozeId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SnoozeResponse'
          description: Notification snooze.
        '400':
          content:
            application/json:
              examples:
                invalid_snooze_id:
                  $ref: '#/components/examples/invalid_snooze_id'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: 'Snooze lookup failed: `invalid_snooze_id` if the supplied `snoozeId` does not match any snooze rule accessible to the calling user.'
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Get a notification snooze for the caller
      tags:
      - User Notifications
      x-extole-bundle: management
      x-extole-visibility: visible
    delete:
      description: Removes the snooze rule identified by `snoozeId` belonging to the calling portal user. Returns the deleted snooze. Notifications previously suppressed by this rule will resume immediately. To delete a snooze for a different user, use `deleteSnoozeByUser`.
      operationId: deleteSnooze
      parameters:
      - in: path
        name: snoozeId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SnoozeResponse'
          description: Deleted notification snooze.
        '400':
          content:
            application/json:
              examples:
                invalid_snooze_id:
                  $ref: '#/components/examples/invalid_snooze_id'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: 'Snooze lookup failed: `invalid_snooze_id` if the supplied `snoozeId` does not match any snooze rule accessible to the calling user.'
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Delete a notification snooze for the caller
      tags:
      - User Notifications
      x-extole-bundle: management
      x-extole-visibility: visible
  /v6/notifications/{userId}:
    get:
      description: Returns the in-portal notifications for the Extole portal user identified by `userId`, sorted newest first. Requires the `USER_SUPPORT` scope. Use the `limit` and `offset` parameters to page through results.
      operationId: listNotificationsByUser
      parameters:
      - in: path
        name: userId
        required: true
        schema:
          type: string
      - in: query
        name: limit
        schema:
          format: int32
          type: integer
      - in: query
        name: offset
        schema:
          format: int32
          type: integer
      - in: query
        name: having_all_tags
        schema:
          items:
            type: string
          type: array
          uniqueItems: true
      - in: query
        name: event_id
        schema:
          type: string
      - in: query
        name: subscription_id
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/NotificationResponse'
                type: array
          description: Notifications for the user.
        '400':
          content:
            application/json:
              examples:
                user_not_found:
                  $ref: '#/components/examples/user_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: 'User lookup failed: `user_not_found` if no Extole portal user with the given `userId` exists within this client.'
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: List notifications for a user
      tags:
      - User Notifications
      x-extole-bundle: management
      x-extole-visibility: visible
  /v6/notifications/{userId}/read:
    get:
      description: Returns the timestamp up to which the Extole portal user identified by `userId` has read their notifications. Requires the `USER_SUPPORT` scope. Use `updateNotificationCursorByUser` to advance the cursor.
      operationId: getNotificationCursorByUser
      parameters:
      - in: path
        name: userId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationCursorResponse'
          description: Notification read cursor.
        '400':
          content:
            application/json:
              examples:
                user_not_found:
                  $ref: '#/components/examples/user_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: 'User lookup failed: `user_not_found` if no Extole portal user with the given `userId` exists within this client.'
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Get notification read cursor for a user
      tags:
      - User Notifications
      x-extole-bundle: management
      x-extole-visibility: visible
    post:
      description: Advances the read cursor to the supplied timestamp for the Extole portal user identified by `userId`, marking all notifications created at or before that time as read. Returns the updated cursor state.
      operationId: updateNotificationCursorByUser
      parameters:
      - in: path
        name: userId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              last_read_event_time: '2025-10-24T02:00:00-07:00'
            schema:
              $ref: '#/components/schemas/NotificationCursorRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationCursorResponse'
          description: Updated notification read cursor.
        '400':
          content:
            application/json:
              examples:
                missing_date_time:
                  $ref: '#/components/examples/missing_date_time'
                user_not_found:
                  $ref: '#/components/examples/user_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: 'Invalid request: `user_not_found` if the `userId` does not correspond to an Extole portal user; `missing_date_time` if no timestamp was supplied in the request body.'
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              

# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/extole/refs/heads/main/openapi/extole-user-notifications-api-openapi.yml