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

Class	Purpose	Where to use	Features
`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:

All three classes implement the TypeB24 interface, which exposes the unified surface:

type TypeB24 = {
  readonly isInit: boolean
  init(): Promise<void>
  destroy(): void

  getLogger(): LoggerInterface
  setLogger(logger: LoggerInterface): void

  get auth(): AuthActions

  // REST API (v2 / v3) — call, callList, fetchList, batch, batchByChunk
  get actions(): ActionsManager

  // Helper utilities (healthCheck, ping)
  get tools(): ToolsManager

  setRestrictionManagerParams(params: RestrictionParams): Promise<void>

  getTargetOrigin(): string
  getTargetOriginWithPath(): Map<ApiVersion, string>

  getHttpClient(version: ApiVersion): TypeHttp
  setHttpClient(version: ApiVersion, client: TypeHttp): void
}

REST methods are reached through actions.v2.* and actions.v3.*:

// $b24 is an instance of B24Frame | B24Hook | B24OAuth

await $b24.actions.v2.call.make(options)         // Promise<AjaxResult>
await $b24.actions.v2.callList.make(options)     // Promise<Result<T[]>>
$b24.actions.v2.fetchList.make(options)          // AsyncGenerator<T[]>
await $b24.actions.v2.batch.make(options)        // Promise<CallBatchResult>
await $b24.actions.v2.batchByChunk.make(options) // Promise<Result<T[]>>

// v3 is symmetric
await $b24.actions.v3.call.make(options)
// ...

await $b24.tools.healthCheck.make({ requestId })  // Promise<boolean>
await $b24.tools.ping.make({ requestId })         // Promise<number>

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 $b24.actions.v2.call.make({
    method: 'crm.contact.get',
    params: { id: 123 }
  })
}

// In an application embedded in Bitrix24
async () => {
  $b24 = await initializeB24Frame()
  const response = await $b24.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:

See B24OAuth for the full constructor signature and refresh-token flow.

// @check-ignore: placeholder params for illustration — real B24OAuthParams required at runtime

import { B24OAuth, EnumAppStatus } from '@bitrix24/b24jssdk'

const $b24 = new B24OAuth(
  { /* B24OAuthParams: applicationToken, userId, memberId, accessToken,
       refreshToken, expires, expiresIn, scope, domain, clientEndpoint,
       serverEndpoint, status (EnumAppStatus.*) */ },
  { clientId: 'your_client_id', clientSecret: 'your_client_secret' }
)

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

// @check-ignore: placeholder params for illustration — real B24OAuthParams required at runtime

import { B24OAuth, EnumAppStatus } from '@bitrix24/b24jssdk'

const $b24 = new B24OAuth(
  { /* B24OAuthParams: see /docs/working-with-the-rest-api/oauth/ */ },
  { clientId: 'your_client_id', clientSecret: 'your_client_secret' }
)

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:

// @check-ignore: top-level return in error-handling illustration

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()

// @check-ignore: top-level return in error-handling illustration

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

Choosing the method

Decision guide for picking between Call, CallList, FetchList, Batch and BatchByChunk in REST API v2 and v3.