CallListV2.make

Overview

When you need to retrieve all records from list methods of REST API version 2 with maximum efficiency and are ready to store the complete dataset in memory, use CallListV2.make().

This method automatically handles pagination and returns all data in a single array.

// Basic usage
import { EnumCrmEntityTypeId } from '@bitrix24/b24jssdk'

const response = await $b24.actions.v2.callList.make({
  method: 'crm.item.list',
  params: {
    entityTypeId:  EnumCrmEntityTypeId.deal,
    filter: { '>opportunity': 10000 }
  },
  idKey: 'id',
  customKeyForResult: 'items',
  requestId: 'unique-request-id'
})

When to Use CallListV2.make()

1. Small to medium data volumes: When the total number of records does not exceed several thousand.
2. Simple processing: When you need simple access to all data at once.
3. Data aggregation: When you need to perform operations on the entire dataset (summation, grouping, etc.).

Method Signature

make<T = unknown>(
  options: ActionCallListV2
): Promise<Result<T[]>>

Parameters

The options object contains the following properties:

Return Value

Promise<Result<T[]>> — a promise that resolves to a Result<T[]> object containing an array of all retrieved elements.

This object provides:

• .getData(): T[] — returns an array of all retrieved elements.
• .isSuccess: boolean — flag indicating successful execution of all requests.
• .getErrorMessages(): string[] — array of error messages.

Key Concepts

Automatic Warning

When calling methods that are available in REST API version 3, the system automatically logs a warning:

"The method {method_name} is available in restApi:v3. It's worth migrating to the new API."

This indicates that you should consider migrating to the newer REST API version.

Performance Optimization

The method implements the Bitrix24 recommended algorithm for efficient work with large data volumes:

1. start: -1: Disables counting the total number of records, significantly speeding up query execution.
2. Filtering by increasing ID: Each subsequent query uses a >ID filter with the ID of the last retrieved element.
3. Automatic data end detection: Requests stop when an empty array is received or the number of elements is less than the page size (50).

REST API v2 Response Structure

In REST API version 2, various methods may return data in different structures:

• Direct array: { result: [...] }
• Grouped array: { result: { items: [...] } }

The customKeyForResult parameter allows you to specify the key where the data is located in the response.

Limitations

• Page size: Fixed limitation of Bitrix24 REST API version 2 — 50 records per request.
• Sorting: The method always adds sorting by idKey in ascending order for correct pagination.
• Only for list methods: Intended only for methods that return data arrays.

Error Handling

Always check the result using isSuccess and handle errors:

const response = await $b24.actions.v2.callList.make({
  method: 'some.method',
  params: { /* some_params */ },
  idKey: 'id',
  customKeyForResult: 'items',
  requestId: 'unique-request-id'
})

if (!response.isSuccess) {
  // Handling error
  console.error(new Error(`Error: ${response.getErrorMessages().join('; ')}`))
  return
}

// Working with a successful result
const data = response.getData()

Examples

Getting all companies with filtering

import { B24Hook, EnumCrmEntityTypeId, LoggerFactory, Text, SdkError, AjaxError } from '@bitrix24/b24jssdk'

type Company = {
  id: number
  title: string
}

const devMode = typeof import.meta !== 'undefined' && (import.meta.dev || import.meta.env?.DEV)
const $logger = LoggerFactory.createForBrowser('Example:AllCrmItems', devMode)
const $b24 = B24Hook.fromWebhookUrl('https://your_domain.bitrix24.com/rest/1/webhook_code/')

async function getCrmItemList(requestId: string): Promise<Company[]> {
  const sixMonthAgo = new Date()
  sixMonthAgo.setMonth((new Date()).getMonth() - 6)
  sixMonthAgo.setHours(0, 0, 0)

  const response = await $b24.actions.v2.callList.make<Company>({
    method: 'crm.item.list',
    params: {
      entityTypeId: EnumCrmEntityTypeId.company,
      filter: {
        // use some filter by title
        '=%title': 'Prime%',
        '>=createdTime': Text.toB24Format(sixMonthAgo) // created at least 6 months ago
      },
      select: ['id', 'title']
    },
    idKey: 'id',
    customKeyForResult: 'items',
    requestId
  })

  if (!response.isSuccess) {
    throw new SdkError({
      code: 'MY_APP_GET_PROBLEM'
      description: `Problem ${response.getErrorMessages().join('; ')}`,
      status: 404
    })
  }

  return response.getData()
}

// Usage
const requestId = 'some-crm-item-list'
try {
  const list = await getCrmItemList(requestId)
  $logger.info(`List [${list?.length}]`, { requestId, list })
} catch (error) {
  if (error instanceof AjaxError) {
    $logger.critical(error.message, { requestId, code: error.code })
  } else {
    $logger.alert('Problem', { requestId, error })
  }
}

Alternatives and Recommendations

• For working with lists: Instead of manually managing pagination use:
  • FetchList — returns an async generator for step-by-step processing of large lists.
• For batch operations: Use Batch to execute up to 50 commands in a single request.
• On the client-side (browser): Use the built-in B24Frame object.