## 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 |
|----------|-----|:-----:|---------|
| `text` (query) | string | no | Text 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 |
| `type` (query) | string | no | Notification 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`](./schema.md). If `types` is passed, `type` is ignored |
| `types` (query) | string \| array | no | Several source modules, comma-separated, `types=crm,mail`, or as an array, `types[]=crm&types[]=mail`. List of modules — [`GET /v1/notifications/schema`](./schema.md). 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 |
| `authors` (query) | string \| array | no | Author 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`](/docs/entities/users/list) |
| `date` (query) | string | no | 24 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 |
| `dateFrom` (query) | string | no | Start of the date range in ISO 8601 format. Applied only together with `dateTo` |
| `dateTo` (query) | string | no | End 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` |
| `lastId` (query) | string | no | Cursor — 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

```bash
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

```bash
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 |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data.chatId` | number, null | ID 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 |
| `data.notifications` | array | Notifications found on the page |
| `data.notifications[].id` | number, null | Notification ID. Passed in `lastId` for the next page and to [`DELETE /v1/notifications/:id`](./delete.md) |
| `data.notifications[].chatId` | number, null | ID of this notification's chat |
| `data.notifications[].authorId` | number, null | Author ID. `0` — a system notification without an author. 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 `crm` |
| `data.notifications[].notifyEvent` | string | Source event of the notification |
| `data.notifications[].notifyTag` | string | The `tag` the notification was sent with |
| `data.notifications[].notifySubTag` | string | The additional `subTag` |
| `data.notifications[].notifyTitle` | string | Notification title |
| `data.notifications[].settingName` | string | Name of the delivery setting under which the notification reached the recipient |
| `data.notifications[].text` | string | Notification text |
| `data.notifications[].notifyRead` | boolean | Whether the notification has been read |
| `data.notifications[].notifyButtons` | string | Notification buttons — a JSON string with an array of buttons, as in the [notification feed](./list.md). A notification without buttons has no such field |
| `data.notifications[].params` | object, null | Additional sender data. Nested keys are returned as the sender wrote them |
| `data.users` | array | Cards of the authors of this page's notifications. Public fields only, without emails and phone numbers |
| `data.users[].id` | number, null | Employee ID. The full card — [Employees](/docs/entities/users) |
| `data.users[].active` | boolean | Whether the employee is active on 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, null | Job title |
| `data.users[].color` | string | Color of the employee's card in the Bitrix24 interface |
| `data.users[].avatar` | string | Avatar URL |
| `data.users[].bot` | boolean | Whether the author is a bot |
| `data.users[].type` | string | Author type, for example `user` |
| `data.totalResults` | number | Number 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 |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | `text` is shorter than 3 characters and no filter is passed |
| 400 | `INVALID_PARAMS` | A parameter that is not in the "Parameters" table is passed |
| 400 | `INVALID_PARAMS` | `lastId` contains something other than digits or is outside the safe integer range |
| 400 | `INVALID_PARAMS` | `authors` contains a value that is not a non-negative integer, or `types` contains an empty value |
| 400 | `INVALID_PARAMS` | A parameter is passed as an array where a string is expected |
| 401 | `MISSING_API_KEY` | `X-Api-Key` is not passed |
| 401 | `TOKEN_MISSING` | The key has no configured tokens |
| 403 | `SCOPE_DENIED` | The key does not have the `im` scope |
| 403 | `BITRIX_ACCESS_DENIED` | Bitrix24 denied access |
| 422 | `BITRIX_ERROR` | Method error on the Bitrix24 side. The Bitrix24 error code is in the `b24Code` field. For example, a date not in ISO 8601 format |
| 429 | `RATE_LIMITED` | Bitrix24 limited the request rate |
| 502 | `BITRIX_UNAVAILABLE` | The Bitrix24 response could not be read |
| 503 | `BITRIX_TIMEOUT` | Bitrix24 did not respond in time |

Full list of common API errors — [Errors](/docs/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

- [Notification feed](./list.md)
- [Notification type dictionary](./schema.md)
- [Delete by id](./delete.md)
- [Employees](/docs/entities/users)
- [Errors](/docs/errors)