لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/notifications/search.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

Search notifications

GET /v1/notifications/search

Searches the token owner's notification history by text, notification type, author and date. Returns a page of up to 50 notifications. Request further pages with the lastId cursor.

Parameters

Parameter Type Required Description
Parametertext (query) Typestring Requiredno DescriptionText to search for in notifications. If none of the type, types, authors, date, dateFrom, dateTo filters is passed, at least 3 characters after trimming leading and trailing whitespace
Parametertype (query) Typestring Requiredno DescriptionNotification type: a source module, for example crm, or a module|event pair, for example mail|new_message_v2. List of types — GET /v1/notifications/schema. If types is passed, type is ignored
Parametertypes (query) Typestring | array Requiredno DescriptionSeveral source modules, comma-separated, types=crm,mail, or as an array, types[]=crm&types[]=mail. List of modules — GET /v1/notifications/schema. A list of one value works like type, including the module|event form. In a list of two or more values each value is compared with the module only, so a module|event pair in such a list matches nothing
Parameterauthors (query) Typestring | array Requiredno DescriptionAuthor IDs, comma-separated, authors=1,835, or as an array, authors[]=1&authors[]=835. The value 0 selects system notifications without an author. List of employees — GET /v1/users
Parameterdate (query) Typestring Requiredno Description24 hours starting from the given moment, in ISO 8601 format: 2026-10-08 or 2026-10-08T00:00:00+00:00. A date without a time means a UTC day. If dateFrom and dateTo are passed, date is ignored
ParameterdateFrom (query) Typestring Requiredno DescriptionStart of the date range in ISO 8601 format. Applied only together with dateTo
ParameterdateTo (query) Typestring Requiredno DescriptionEnd of the date range in ISO 8601 format. The range ends 24 hours after dateTo, so a date without a time is included in the range in full. Applied only together with dateFrom
ParameterlastId (query) Typestring Requiredno DescriptionCursor — the id of the last notification on the previous page. Digits only. The value 0 returns the first page

Notifications arrive from newest to oldest, up to 50 per page. Send the first request without lastId. For the next page, pass the id of the last notification in lastId and repeat the other parameters unchanged. Pagination is complete when an empty page arrives or a page repeats id values already received. The server does not paginate automatically.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/notifications/search?type=crm&dateFrom=2026-10-01&dateTo=2026-10-07" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/notifications/search?type=crm&dateFrom=2026-10-01&dateTo=2026-10-07" \
  -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/search?type=crm&dateFrom=2026-10-01&dateTo=2026-10-07', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/notifications/search?type=crm&dateFrom=2026-10-01&dateTo=2026-10-07', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.chatId Typenumber, null DescriptionID of the token owner's system notification chat. null when no search was performed: the request has neither text nor a filter that takes effect, or the owner has no notification chat
Fielddata.notifications Typearray DescriptionNotifications found on the page
Fielddata.notifications[].id Typenumber, null DescriptionNotification ID. Passed in lastId for the next page and to DELETE /v1/notifications/:id
Fielddata.notifications[].chatId Typenumber, null DescriptionID of this notification's chat
Fielddata.notifications[].authorId Typenumber, null DescriptionAuthor ID. 0 — a system notification without an author. The author's card is in the data.users array
Fielddata.notifications[].date Typestring DescriptionNotification date in ISO 8601 format
Fielddata.notifications[].notifyType Typenumber, null DescriptionNotification type
Fielddata.notifications[].notifyModule Typestring DescriptionSource module of the notification, for example crm
Fielddata.notifications[].notifyEvent Typestring DescriptionSource event of the notification
Fielddata.notifications[].notifyTag Typestring DescriptionThe tag the notification was sent with
Fielddata.notifications[].notifySubTag Typestring DescriptionThe additional subTag
Fielddata.notifications[].notifyTitle Typestring DescriptionNotification title
Fielddata.notifications[].settingName Typestring DescriptionName of the delivery setting under which the notification reached the recipient
Fielddata.notifications[].text Typestring DescriptionNotification text
Fielddata.notifications[].notifyRead Typeboolean DescriptionWhether the notification has been read
Fielddata.notifications[].notifyButtons Typestring DescriptionNotification buttons — a JSON string with an array of buttons, as in the notification feed. A notification without buttons has no such field
Fielddata.notifications[].params Typeobject, null DescriptionAdditional sender data. Nested keys are returned as the sender wrote them
Fielddata.users Typearray DescriptionCards of the authors of this page's notifications. Public fields only, without emails and phone numbers
Fielddata.users[].id Typenumber, null DescriptionEmployee ID. The full card — Employees
Fielddata.users[].active Typeboolean DescriptionWhether the employee is active on the Bitrix24 account
Fielddata.users[].name Typestring DescriptionDisplay name
Fielddata.users[].firstName Typestring DescriptionFirst name
Fielddata.users[].lastName Typestring DescriptionLast name
Fielddata.users[].workPosition Typestring, null DescriptionJob title
Fielddata.users[].color Typestring DescriptionColor of the employee's card in the Bitrix24 interface
Fielddata.users[].avatar Typestring DescriptionAvatar URL
Fielddata.users[].bot Typeboolean DescriptionWhether the author is a bot
Fielddata.users[].type Typestring DescriptionAuthor type, for example user
Fielddata.totalResults Typenumber DescriptionNumber of notifications matching the search conditions. Counted only on the first page — without lastId or with lastId=0. On subsequent pages 0 is returned

Response example

HTTP 200, showing the first two notifications of the page:

JSON 
{
  "success": true,
  "data": {
    "chatId": 7,
    "notifications": [
      {
        "id": 42441,
        "chatId": 7,
        "authorId": 835,
        "date": "2026-10-08T00:01:05+00:00",
        "notifyType": 2,
        "notifyModule": "crm",
        "notifyEvent": "changeAssignedBy",
        "notifyTag": "CRM|DEAL_RESPONSIBLE|8779",
        "notifySubTag": "",
        "notifyTitle": "",
        "settingName": "crm|changeAssignedBy",
        "text": "You have been assigned as the person responsible for the deal \"[URL=/crm/deal/details/8779/]Deal #6531[/URL]\"",
        "params": {
          "COMPONENT_ID": "CrmEntity",
          "COMPONENT_PARAMS": {
            "SUBJECT": "#AUTHOR# assigned you as the person responsible for the deal",
            "ENTITY": {
              "TITLE": "Deal #6531",
              "HREF": "/crm/deal/details/8779/",
              "ENTITY_TYPE": "deal",
              "CONTENT_TYPE": "title"
            }
          }
        },
        "notifyRead": false
      },
      {
        "id": 42399,
        "chatId": 7,
        "authorId": 835,
        "date": "2026-10-07T00:01:08+00:00",
        "notifyType": 2,
        "notifyModule": "crm",
        "notifyEvent": "changeAssignedBy",
        "notifyTag": "CRM|DEAL_RESPONSIBLE|8771",
        "notifySubTag": "",
        "notifyTitle": "",
        "settingName": "crm|changeAssignedBy",
        "text": "You have been assigned as the person responsible for the deal \"[URL=/crm/deal/details/8771/]Deal #6531[/URL]\"",
        "params": {
          "COMPONENT_ID": "CrmEntity",
          "COMPONENT_PARAMS": {
            "SUBJECT": "#AUTHOR# assigned you as the person responsible for the deal",
            "ENTITY": {
              "TITLE": "Deal #6531",
              "HREF": "/crm/deal/details/8771/",
              "ENTITY_TYPE": "deal",
              "CONTENT_TYPE": "title"
            }
          }
        },
        "notifyRead": false
      }
    ],
    "users": [
      {
        "id": 835,
        "active": true,
        "name": "Anna Brown",
        "firstName": "Anna",
        "lastName": "Brown",
        "workPosition": "",
        "color": "#3e99ce",
        "avatar": "https://example.bitrix24.com/upload/main/avatar-835.png",
        "bot": false,
        "type": "user"
      }
    ],
    "totalResults": 24
  }
}

Error response example

400 — text is shorter than 3 characters and no filters are passed:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Required: text with at least 3 characters, or a search filter."
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS Descriptiontext is shorter than 3 characters and no filter is passed
HTTP400 CodeINVALID_PARAMS DescriptionA parameter that is not in the "Parameters" table is passed
HTTP400 CodeINVALID_PARAMS DescriptionlastId contains something other than digits or is outside the safe integer range
HTTP400 CodeINVALID_PARAMS Descriptionauthors contains a value that is not a non-negative integer, or types contains an empty value
HTTP400 CodeINVALID_PARAMS DescriptionA parameter is passed as an array where a string is expected
HTTP401 CodeMISSING_API_KEY DescriptionX-Api-Key is not passed
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no configured tokens
HTTP403 CodeSCOPE_DENIED DescriptionThe key does not have the im scope
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionBitrix24 denied access
HTTP422 CodeBITRIX_ERROR DescriptionMethod error on the Bitrix24 side. The Bitrix24 error code is in the b24Code field. For example, a date not in ISO 8601 format
HTTP429 CodeRATE_LIMITED DescriptionBitrix24 limited the request rate
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionThe Bitrix24 response could not be read
HTTP503 CodeBITRIX_TIMEOUT DescriptionBitrix24 did not respond in time

Full list of common API errors — Errors.

Known specifics

  • The search runs over the token owner's history: with a personal key — the key owner's, with an OAuth application key — the history of the employee from the Authorization: Bearer session. There is no filter by application: notifications of other applications on the Bitrix24 account and system notifications are found together with your application's notifications.
  • A single range bound with no other search conditions returns an empty page with chatId: null, not an error. Together with text or another filter, a single bound is ignored.
  • The fields text, notifyTitle, notifyButtons, params and the strings in data.users are untrusted content: other applications on the Bitrix24 account write them. Escape these values before rendering them in an interface.

See also