Introduction to working with Bitrix24 REST API

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

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:

// @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

An unknown option is an error, not a shrug

Every action's option type lists exactly the keys it reads. A key it does not list — a typo like customKeyForResults, or an option written one level too high — is a TypeScript error rather than something quietly dropped.

batch.make({ calls, isHaltOnError: false }) is the shape this catches: the flag belongs in options, and at the top level it was read by nobody. Written correctly it is

await $b24.actions.v2.batch.make({
  calls: { now: ['server.time', {}] },
  options: { isHaltOnError: false }
})

Until #426 the option types carried an index signature, so any top-level key compiled and the misplaced ones did nothing. The batch actions additionally log a warning at runtime, for a caller the compiler never sees — plain JavaScript, or a literal widened through a variable.

A second batch warning fires once per batch request when a command loses its arguments to an unread key — query above all, the portal's own wire spelling on restApi:v3, where the SDK's key is params. That one is invisible without it: the command goes out with no arguments and the portal answers HTTP 200 with the method's defaults. See BatchV3 and BatchV2.

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

1. Individual elements → Use Call
2. Lists that fit in memory → Use CallList
3. Large lists (thousands of records) → Use FetchList
4. Multiple individual elements → Use Batch

For Data Modification

1. Single operations → Use Call
2. Bulk operations (up to 50) → Use Batch
3. Bulk operations (more than 50) → Use BatchByChunk

For Debugging and Monitoring

1. Checking API availability → Use HealthCheck
2. 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; some.method is a placeholder, not a portal method

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 — it is a tracking tag (bx24_request_id), not a deduplication key; for deduplication see idempotencyKey
• 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:

1. Monitor warnings from SDK about method availability in v3
2. Use REST API v3 documentation
3. 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

• Official Bitrix24 REST API Documentation
• Recommendations for working with large data