For AI agents: markdown of this page — /docs-content-en/entities/recurring-deals/search.md documentation index — /llms.txt

Search recurring deals

POST /v1/recurring-deals/search

Finds deal recurrence settings using conditions in the request body. Use it to filter schedules and retrieve selected fields.

For selections up to 5000 records, use List recurring deals. Search accepts its conditions in JSON and can split a wide date filter into intervals.

Request body fields

Field Type Required Description
Fieldfilter Typeobject RequiredNo DescriptionFilter by fields from Recurring deal fields.
Filtering syntax. Example body field: "filter":{"active":false}
Fieldsort Typestring / object / string[] RequiredNo DescriptionSort fields. id sorts ascending, -id descending
Fieldorder Typeobject RequiredNo DescriptionAlternative to sort, for example {"id":"desc"}
Fieldselect Typestring / string[] RequiredNo DescriptionResponse fields. A comma-separated string or an array of names
Fieldlimit Typenumber / string RequiredNo DescriptionSelection size, default 50, maximum 5000. A numeric string is also accepted
Fieldoffset Typenumber RequiredNo DescriptionOffset from the start of the selection. A value greater than zero is incompatible with automatic splitting of a date range wider than 14 days. Use autoWindow: false with sort: "id" for pagination
FieldautoWindow Typeboolean RequiredNo DescriptionSet to false to disable automatic splitting of a wide date filter into windows
FieldwithTotal Typeboolean RequiredNo DescriptionRequests the total count in meta.total

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/recurring-deals/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filter":{"active":false},"sort":"id","select":["id","dealId","basedId","active","nextExecution","lastExecution","counterRepeat","startDate","categoryId","isLimit","limitRepeat","limitDate","params"],"limit":2,"withTotal":true}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/recurring-deals/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"filter":{"active":false},"sort":"id","select":["id","dealId","basedId","active","nextExecution","lastExecution","counterRepeat","startDate","categoryId","isLimit","limitRepeat","limitDate","params"],"limit":2,"withTotal":true}'

JavaScript — personal key

javascript 
const response = await fetch('https://vibecode.bitrix24.com/v1/recurring-deals/search', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({"filter":{"active":false},"sort":"id","select":["id","dealId","basedId","active","nextExecution","lastExecution","counterRepeat","startDate","categoryId","isLimit","limitRepeat","limitDate","params"],"limit":2,"withTotal":true}),
})
const result = await response.json()
if (!result.success) throw new Error(result.error.message)
console.log(result.data)

JavaScript — OAuth application

javascript 
const response = await fetch('https://vibecode.bitrix24.com/v1/recurring-deals/search', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({"filter":{"active":false},"sort":"id","select":["id","dealId","basedId","active","nextExecution","lastExecution","counterRepeat","startDate","categoryId","isLimit","limitRepeat","limitDate","params"],"limit":2,"withTotal":true}),
})
const result = await response.json()
if (!result.success) throw new Error(result.error.message)
console.log(result.data)

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionWhether the request succeeded
Fielddata Typeobject[] DescriptionRecurrence settings. See recurring deal fields
Fieldmeta.total Typenumber DescriptionTotal matching settings, when returned
Fieldmeta.hasMore Typeboolean DescriptionWhether more records are available
Fieldmeta.durationMs Typenumber DescriptionExecution time in milliseconds, when returned
Fieldmeta.warnings Typeobject[] DescriptionWarnings, when returned. Unknown select fields can be ignored in a successful request
Fieldmeta.autoWindowed Typeboolean DescriptionWhether date windowing was applied
Fieldmeta.windowCount Typenumber DescriptionNumber of date intervals, when windowing is applied
Fieldmeta.windowErrors Typenumber DescriptionNumber of failed intervals, when failures occur
Fieldmeta.windowErrorSample Typeobject DescriptionFirst interval error with code and message, on partial failure
Fieldmeta.pageErrorSample Typeobject DescriptionSample subpage error when the returned selection is incomplete

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 1,
      "dealId": 575,
      "basedId": 573,
      "active": false,
      "nextExecution": null,
      "lastExecution": "2020-06-16T22:00:00.000Z",
      "counterRepeat": 2,
      "startDate": "2020-06-15",
      "categoryId": 1,
      "isLimit": "T",
      "limitRepeat": 2,
      "limitDate": null,
      "params": {
        "mode": "multiple",
        "singleBeforeStartDateValue": 0,
        "singleBeforeStartDateType": "day",
        "multipleType": "day",
        "multipleInterval": 1,
        "offsetBeginDateType": "day",
        "offsetBeginDateValue": 1,
        "offsetCloseDateType": "day",
        "offsetCloseDateValue": 1
      }
    },
    {
      "id": 3,
      "dealId": 3865,
      "basedId": 3863,
      "active": false,
      "nextExecution": null,
      "lastExecution": "2021-01-12T22:00:00.000Z",
      "counterRepeat": 2,
      "startDate": "2021-01-14",
      "categoryId": 0,
      "isLimit": "D",
      "limitRepeat": null,
      "limitDate": "2021-01-13",
      "params": {
        "mode": "single",
        "singleBeforeStartDateValue": 1,
        "singleBeforeStartDateType": "day",
        "multipleType": "day",
        "multipleInterval": 1,
        "offsetBeginDateType": "day",
        "offsetBeginDateValue": 0,
        "offsetCloseDateType": "day",
        "offsetCloseDateValue": 0
      }
    }
  ],
  "meta": {
    "total": 4,
    "hasMore": true,
    "durationMs": 123
  }
}

Error response example

400 — unknown filter field:

JSON 
{
  "success": false,
  "error": {
    "code": "UNKNOWN_FILTER_FIELD",
    "message": "Unknown filter field 'madeUp' for entity 'recurring-deals'. Available: id, dealId, basedId, active, nextExecution, lastExecution, counterRepeat, startDate, categoryId, isLimit, limitRepeat, limitDate"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_REQUEST DescriptionThe request body is not a JSON object
HTTP400 CodeINVALID_LIMIT Descriptionlimit cannot be interpreted as a finite number. Numbers and numeric strings are accepted
HTTP400 CodeINVALID_SELECT_TYPE Descriptionselect is not a string or an array of strings
HTTP400 CodeINVALID_SORT_TYPE Descriptionsort is not a string, object or array of strings
HTTP400 CodeUNKNOWN_FILTER_FIELD DescriptionThe filter references an unknown field. See the error message and field definitions
HTTP400 CodeINVALID_FILTER_FIELD DescriptionA field name starts with the unsupported prefix @ or !@
HTTP400 CodeINVALID_FILTER_OPERATOR DescriptionAn unknown operator, an empty condition object, or a logical condition using $or or $and
HTTP400 CodeINVALID_DUPLICATE_FILTER_FIELD DescriptionTwo conditions map to the same filter condition. Supply only one
HTTP400 CodeINVALID_SORT_FIELD DescriptionSorting uses a forbidden name: __proto__, constructor or prototype
HTTP400 CodeUNKNOWN_SORT_FIELD DescriptionSorting references an unknown field
HTTP400 CodeINVALID_SORT_DIRECTION DescriptionA sort direction is not one of the strings asc, desc, ASC, DESC or the numbers 1, -1
HTTP400 CodeINVALID_FILTER_SHAPE Descriptionfilter is not an object
HTTP400 CodeUNSTABLE_OFFSET_PAGINATION Descriptionoffset > 0 is combined with automatic splitting of a date range wider than 14 days. Use autoWindow: false with sort: "id" for pagination
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeTOKEN_MISSING DescriptionNo Bitrix24 access tokens are configured
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the crm scope
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionBitrix24 denied access, including a missing required scope
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the operation or a plan restriction applies. See error.message
HTTP503 CodeBITRIX_TIMEOUT DescriptionBitrix24 did not respond in time. Retry after the interval in Retry-After
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionA connection to Bitrix24 could not be established
HTTP429 CodeRATE_LIMITED DescriptionThe request rate limit was exceeded. The effective limit is in the x-ratelimit-limit header. Retry after the interval in the Retry-After header

For the full list of common API errors, see Error codes.

Known specifics

The response can include settings with active: false. To retrieve active schedules only, filter by active: true.

See also