Introduction to working with Bitrix24 REST API

We are still updating this page. Some data may be missing here — we will complete it shortly.

Overview

The SDK for working with Bitrix24 REST API provides a set of tools for interacting with Bitrix24 API from JavaScript/TypeScript applications.

The library supports both REST API version 2 (deprecation process has started but still widely used) and the new version 3 (implementation process has started).

SDK Architecture

The SDK is built on three main classes that inherit from a common base class and provide a unified interface for working with REST API:

Three Classes for Different Usage Scenarios

Класс	Назначение	Где использовать	Особенности
`B24Frame`	Working from applications embedded in the Bitrix24 interface	Client-side (browser)	Automatically available in Bitrix24 application iframe, uses current user token
`B24Hook`	Working from standalone server applications via webhook	Server-side	Uses permanent webhook token, cannot be used in browser
`B24OAuth`	Working from standalone server applications via OAuth 2.0	Server-side	Uses OAuth token with refresh capability, cannot be used in browser

Common Interface

All three classes inherit from a common base class and provide the same set of methods:

// Unified interface for all classes
interface B24Base {
  actions: {
    v2: {
      call: { make(options: ActionCallV2): Promise<AjaxResult> }
      callList: { make(options: ActionCallListV2): Promise<Result<T[]>> }
      fetchList: { make(options: ActionFetchListV2): AsyncGenerator<T[]> }
      batch: { make(options: ActionBatchV2): Promise<CallBatchResult> }
      batchByChunk: { make(options: ActionBatchByChunkV2): Promise<Result<T[]>> }
    }
    // ... other methods
  }
  
  tools: {
    healthCheck: { make(options?: { requestId?: string }): Promise<boolean> }
    ping: { make(options?: { requestId?: string }): Promise<number> }
    // ... other methods
  }
}

// Unified interface for all classes
interface B24Base {
  actions: {
    v3: {
      call: { make(options: ActionCallV3): Promise<AjaxResult> }
      callList: { make(options: ActionCallListV3): Promise<Result<T[]>> }
      fetchList: { make(options: ActionFetchListV3): AsyncGenerator<T[]> }
      batch: { make(options: ActionBatchV3): Promise<CallBatchResult> }
      batchByChunk: { make(options: ActionBatchByChunkV3): Promise<Result<T[]>> }
    }
    // ... other methods
  }
  
  tools: {
    healthCheck: { make(options?: { requestId?: string }): Promise<boolean> }
    ping: { make(options?: { requestId?: string }): Promise<number> }
    // ... other methods
  }
}

Key Features

Main API Methods

Call — basic method for calling any REST API methods
CallList — automatic retrieval of all data from list methods with pagination
FetchList — step-by-step processing of large data volumes via AsyncGenerator
Batch — execution of up to 50 commands in a single request
BatchByChunk — automatic splitting of large command sets into batches

Helper Tools

HealthCheck — checking REST API availability
Ping — measuring API response time

Choosing the Right Class

For Client Applications (Browser) client-side

Use B24Frame — it's available in Bitrix24 application iframes:

// In an application embedded in Bitrix24
async () => {
  $b24 = await initializeB24Frame()
  const response = await B24Frame.actions.v2.call.make({
    method: 'crm.contact.get',
    params: { id: 123 }
  })
}

// In an application embedded in Bitrix24
async () => {
  $b24 = await initializeB24Frame()
  const response = await B24Frame.actions.v3.call.make({
    method: 'tasks.task.get',
    params: { id: 123 }
  })
}

For Server Applications with Permanent Access server-side

Use B24Hook with webhook:

import { B24Hook } from '@bitrix24/b24jssdk'

const $b24 = B24Hook.fromWebhookUrl('https://your_domain.bitrix24.com/rest/1/webhook_code/')

const response = await $b24.actions.v2.call.make({
  method: 'crm.contact.get',
  params: { id: 123 },
  requestId: 'server-request'
})

import { B24Hook } from '@bitrix24/b24jssdk'

const $b24 = B24Hook.fromWebhookUrl('https://your_domain.bitrix24.com/rest/1/webhook_code/')

const response = await $b24.actions.v3.call.make({
  method: 'tasks.task.get',
  params: { id: 123 },
  requestId: 'server-request'
})

For Server Applications with OAuth Authentication server-side authentication

Use B24OAuth:

import { B24OAuth } from '@bitrix24/b24jssdk'

const $b24 = B24OAuth.fromConfig({
  domain: 'your_domain.bitrix24.com',
  clientId: 'your_client_id',
  clientSecret: 'your_client_secret',
  accessToken: 'current_token',
  refreshToken: 'refresh_token'
})

const response = await $b24.actions.v2.call.make({
  method: 'crm.contact.get',
  params: { id: 123 },
  requestId: 'oauth-request'
})

import { B24OAuth } from '@bitrix24/b24jssdk'

const $b24 = B24OAuth.fromConfig({
  domain: 'your_domain.bitrix24.com',
  clientId: 'your_client_id',
  clientSecret: 'your_client_secret',
  accessToken: 'current_token',
  refreshToken: 'refresh_token'
})

const response = await $b24.actions.v3.call.make({
  method: 'tasks.task.get',
  params: { id: 123 },
  requestId: 'oauth-request'
})

Common Methods (Available in All Classes)

Method Architecture

Method	Return Value	Memory	Usage	Suitable for
`Call`	`Promise<AjaxResult>`	Minimum	Single calls	Retrieving individual elements, calling methods without pagination
`CallList`	`Promise<Result<T[]>>`	All data in memory	`await response.getData()`	Small to medium data volumes, when all data is needed at once
`FetchList`	`AsyncGenerator<T[]>`	Processing in parts	`for await (const chunk of generator)`	Large data volumes, stream processing, limited memory
`Batch`	`Promise<CallBatchResult>`	Depends on volume	Batch operations up to 50 commands	Bulk operations, network request optimization

Automatic Warnings
SDK automatically tracks usage of methods available in REST API v3:
"The method {method_name} is available in restApi:v3. It's worth migrating to the new API."
This allows gradual migration from deprecated API v2 to modern v3.

Method Selection Recommendations

For Data Retrieval

Individual elements → Use Call
Small lists (up to 1000 records) → Use CallList
Large lists (thousands of records) → Use FetchList
Multiple individual elements → Use Batch

For Data Modification

Single operations → Use Call
Bulk operations (up to 50) → Use Batch
Bulk operations (more than 50) → Use BatchByChunk

For Debugging and Monitoring

Checking API availability → Use HealthCheck
Measuring response speed → Use Ping

Best Practices

Error Handling

Always check isSuccess and handle errors:

const response = await $b24.actions.v2.call.make({
  method: 'some.method',
  params: { /* parameters */ },
  requestId: 'unique-id'
})

if (!response.isSuccess) {
  console.error('Error:', response.getErrorMessages().join('; '))
  // Additional error handling logic
  return
}

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

const response = await $b24.actions.v3.call.make({
  method: 'some.method',
  params: { /* parameters */ },
  requestId: 'unique-id'
})

if (!response.isSuccess) {
  console.error('Error:', response.getErrorMessages().join('; '))
  // Additional error handling logic
  return
}

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

Request Management

requestId — always specify a unique request identifier for tracking and deduplication
Logging — use built-in logging mechanisms for debugging
Timeouts — configure timeouts for long operations

Migration from REST API v2 to v3

Bitrix24 is gradually transitioning to REST API version 3. It is recommended to:

Monitor warnings from SDK about method availability in v3
Use REST API v3 documentation
Plan migration of existing projects

What's Next?

Common methods — You have already familiarized yourself with common methods available in all three classes
Individual features — Each class (B24Frame, B24Hook, B24OAuth) has its own unique methods and features that will be described in separate documentation sections
Usage examples — See specific examples for each usage scenario

Additional Resources

Call

A method for making Bitrix24 REST API version 2 calls.