For AI agents: markdown of this page — /docs-content-en/notifications/list.md documentation index — /llms.txt

Notification feed

GET /v1/notifications

Returns a page of the token owner's notifications together with the unread counter. Pages are traversed with a cursor, and the page size is set by the limit parameter.

Parameters

Parameter Type Required Default Description
limit (query) number no 50 Page size, from 1 to 50. Values 0 and above 50 are brought to the nearest bound and the original comes back in meta.requestedLimit. A negative, fractional or non-numeric value returns 400 INVALID_LIMIT
lastId (query) number no — The id of the last notification on the previous page. Sent only together with lastType
lastType (query) number no — Traversal stage of the feed: 1 — confirmations, 3 — regular notifications. Sent only together with lastId
convertText (query) string no off Conversion of the notification text. The values true, 1, y turn it on, false, 0, n turn it off. The value is case-insensitive

The first request goes without a cursor — the page is taken from the start of the feed. For the next page, send the id of the last notification in lastId together with lastType. The traversal order and the end-of-feed indicator are in the "Known specifics" section.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/notifications?limit=20" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/notifications?limit=20" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/notifications?limit=20', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data } = await res.json()
console.log('Unread:', data.totalUnreadCount)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/notifications?limit=20', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()
console.log('Unread:', data.totalUnreadCount)

Response fields

Field Type Description
success boolean Always true on success
data.notifications array Notifications on the page
data.notifications[].id number, null Notification identifier. Pass it in lastId for the next page and to DELETE /v1/notifications/:id
data.notifications[].chatId number, null Identifier of the chat this notification belongs to
data.notifications[].authorId number, null Author identifier. The author's card is in the data.users array
data.notifications[].date string Notification date in ISO 8601 format
data.notifications[].notifyType number, null Notification type
data.notifications[].notifyModule string Source module of the notification, for example rest
data.notifications[].notifyEvent string Source event of the notification
data.notifications[].notifyTag string The tag the notification was sent with
data.notifications[].notifySubTag string Additional subTag
data.notifications[].notifyTitle string Notification title
data.notifications[].settingName string Name of the delivery setting the notification arrived through
data.notifications[].text string Notification text
data.notifications[].notifyRead boolean Whether the notification has been read
data.notifications[].notifyButtons array Notification buttons. The field is absent on a notification without buttons
data.notifications[].params object, null Extra data from the sender. The keys inside are the ones the sending application wrote
data.users array Cards of the authors of the notifications on this page
data.users[].id number, null User identifier. Full card — Users
data.users[].active boolean Whether the user is active in the Bitrix24 account
data.users[].name string Display name
data.users[].firstName string First name
data.users[].lastName string Last name
data.users[].workPosition string Job position
data.users[].color string Color of the user card in the Bitrix24 interface
data.users[].avatar string Avatar link
data.users[].bot boolean Whether the author is a bot
data.users[].type string Author type, for example user
data.totalCount number Notification counter of the feed
data.totalUnreadCount number Unread notification counter
data.chatId number, null Identifier of the system notification chat
data.hasMore boolean true when the page is filled up to meta.appliedLimit
meta.appliedLimit number Page size the request ran with
meta.requestedLimit number The original limit value before clamping. Present only when the value was changed

Response example

HTTP 200:

JSON 
{
  "success": true,
  "data": {
    "notifications": [
      {
        "id": 38963,
        "chatId": 3113,
        "authorId": 1297,
        "date": "2026-08-13T09:00:00+00:00",
        "notifyType": 2,
        "notifyModule": "rest",
        "notifyEvent": "rest_notify",
        "notifyTag": "MP|12345|DEAL_1024",
        "notifySubTag": "MP|12345|DEAL|1024",
        "notifyTitle": "",
        "settingName": "rest|rest_notify",
        "text": "Deal #1024 moved to the Paid stage",
        "params": null,
        "notifyRead": false
      },
      {
        "id": 38959,
        "chatId": 3113,
        "authorId": 1,
        "date": "2026-08-13T08:41:12+00:00",
        "notifyType": 1,
        "notifyModule": "im",
        "notifyEvent": "confirm",
        "notifyTag": "",
        "notifySubTag": "",
        "notifyTitle": "",
        "settingName": "im|confirm",
        "text": "Confirm your attendance at the meeting",
        "notifyButtons": [
          { "TITLE": "Yes", "VALUE": "Y", "COMMAND": "confirm" },
          { "TITLE": "No", "VALUE": "N", "COMMAND": "confirm" }
        ],
        "params": null,
        "notifyRead": true
      }
    ],
    "users": [
      {
        "id": 1297,
        "active": true,
        "name": "Emma Hayes",
        "firstName": "Emma",
        "lastName": "Hayes",
        "workPosition": "Sales Manager",
        "color": "#1eb4aa",
        "avatar": "https://example.bitrix24.com/upload/main/avatar-1297.png",
        "bot": false,
        "type": "user"
      },
      {
        "id": 1,
        "active": true,
        "name": "John Carter",
        "firstName": "John",
        "lastName": "Carter",
        "workPosition": "Head of Department",
        "color": "#df532d",
        "avatar": "https://example.bitrix24.com/upload/main/avatar-1.png",
        "bot": false,
        "type": "user"
      }
    ],
    "totalCount": 15,
    "totalUnreadCount": 1,
    "chatId": 3113,
    "hasMore": false
  },
  "meta": {
    "appliedLimit": 20
  }
}

Error response example

400 — limit is not an integer:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_LIMIT",
    "message": "limit must be an integer in 1..50"
  }
}

Errors

HTTP Code Description
400 INVALID_LIMIT limit is negative, fractional, non-numeric or was not sent as a string
400 VALIDATION_ERROR Half of the cursor was sent, lastType is outside the values 1 and 3, lastId is beyond the safe integer range, convertText holds an unrecognized value, or a parameter was not sent as a string
403 SCOPE_DENIED The key lacks the im scope
401 TOKEN_MISSING The key has no configured tokens
429 RATE_LIMITED Feed reading rate exceeded — up to 600 requests per minute per Bitrix24 account
502 BITRIX_UNAVAILABLE The Bitrix24 response could not be read
422 BITRIX_ERROR The method failed on the Bitrix24 side; the account's own code is in b24Code

Full list of common API errors — Errors.

Known specifics

  • The feed belongs to the token owner — the operation has no "whose feed to read" parameter. A personal key returns the feed of the key owner. The feed of a specific user is available only with an OAuth-application key carrying the Authorization: Bearer header: the user session decides whose feed it is.
  • The feed is not filtered by application: notifications of other applications on the Bitrix24 account and system notifications arrive alongside your own. Select yours by notifyTag or notifyModule on the client side.
  • A wrongly chosen lastType raises no error — the same page comes back. Traversal order: an empty page means the end. If a page brought no new id at all, repeat the same lastId with the other lastType value, and only when that one also brings no new id treat the traversal as finished. Keep your own ceiling on the number of pages: a complete traversal of the feed is not guaranteed by the contract.
  • hasMore: false means the page came back shorter than the requested limit. That is usually the end of the feed, but a short page also arrives in the middle of a traversal, so the reliable end indicator is an empty page.
  • totalCount can be noticeably larger than the number of notifications the feed hands out during a traversal. It cannot drive pagination.
  • data.chatId and data.notifications[].chatId are different values. The first is the system notification chat, the second is the chat of a particular notification.
  • The unread counter is read without pulling a page — with a limit=1 request. On a non-empty feed such a request always returns hasMore: true.
  • The fields text, notifyTitle, notifyButtons, params and the strings in data.users are untrusted content: other applications of the Bitrix24 account write them. Escape these values before rendering them in an interface.
  • Counters Bitrix24 did not send are replaced with 0, 0 and null. A counter it did send is passed through as is, so totalCount can be non-zero on an empty page. There is no separate empty-feed indicator — check the length of notifications.

See also