Skip to main content
Bitrix24 is a comprehensive business management platform that combines CRM, project management, communication tools, and business automation features. It provides solutions for sales, marketing, customer service, and team collaboration in a single integrated platform.

Configuring Bitrix24 as a Source

In the Sources tab, click on the “Add source” button located on the top right of your screen. Then, select the Bitrix24 option from the list of connectors. Click Next and you’ll be prompted to add your access.

1. Add account access

The connector supports two authentication modes:
  • OAuth (default): Install the Nekt app on your Bitrix24 instance using the install button, provide your Domain URL (e.g. https://yourworkspace.bitrix24.com/), and sign in with Bitrix24 to authorize Nekt.
  • Webhook: Provide an Incoming webhook URL for your Bitrix24 portal. Check the Bitrix documentation for how to create an incoming webhook and copy its URL.
The following configurations are available:
  • Authentication mode: oauth (default) or webhook.
  • Domain URL: The domain URL of your Bitrix24 workspace. Required in OAuth mode; in webhook mode the domain is read from the webhook URL.
  • Incoming webhook URL: The Bitrix24 incoming webhook URL used for API calls. Required in webhook mode.
  • Extract deal contacts: (Default: false) When enabled, performs an additional API call per deal to retrieve related contact IDs. Enable only if your deals have multiple clients and you need that list.
  • Enable deal comments stream: (Default: false) When enabled, the deal_comments stream becomes available. Selecting it triggers one extra API call per deal to fetch comments. Enable only if needed, as it increases extraction time.
  • Enable deal products stream: (Default: false) When enabled, the deal_products stream becomes available. Selecting it triggers one extra API call per deal to fetch products. Enable only if needed, as it increases extraction time.
  • Enable quote products stream: (Default: false) When enabled, the quote_products stream becomes available. Selecting it triggers one extra API call per quote to fetch its products. Enable only if needed, as it increases extraction time.
  • Operating time threshold: (Default: 200) If Bitrix returns an “operating time” greater than this value (in seconds), the tap will pause for that duration before continuing. Use this to respect rate limits.
  • Filter deal category IDs: (Optional) List of Bitrix deal category IDs (funnels). If set, only deals from these categories are extracted. Leave empty to sync all deals.
  • SPA Column Name Overrides: (Advanced, optional) Map specific Bitrix SPA field codes to exact column names, to control how case-colliding custom fields are separated. Example: {"ufCrm10Fotoprincipal": "ufCrm10Fotoprincipal_2"}. Leave empty to use automatic collision resolution.
  • Enable BI reports: (Default: false) Enables the Bitrix24 BI Connector report streams (such as Open Channels session statistics). The BI Connector is a separate integration from the webhook and requires its own key.
  • BI connector key: Bitrix24 BI connector key, generated under CRM -> Analytics -> BI analytics -> Manage keys. Required when ‘Enable BI reports’ is on.
  • BI reports start date: First day to pull BI report data from on the initial sync.
  • BI reports window size (days): (Default: 30) Size in days of each BI Connector request window. Smaller windows reduce per-request row counts to stay under plan limits.
  • BI reports lookback (days): (Default: 30) Number of days re-pulled before the saved bookmark on incremental BI report syncs, to capture updates to recently created sessions.
Scopes that must be included in your webhook (or granted to the Nekt app in OAuth mode) so Nekt can retrieve data:
  • CRM: crm — contacts, companies, deals, deal categories, leads, activities, products, status list, SPA types (and optionally deal comments, deal products).
  • Users: user, user_brief, user_basic — user list and profile data.
  • Company structure: departments — departments.
  • Telephony: telephony — calls (Voximplant statistics).
  • Open lines: imopenlines — open line configurations.
Once you’re done, click Next.

2. Select streams

Choose which data streams you want to sync. Visibility depends on your webhook scopes and on the optional settings above (deal comments, deal products). You can select entire groups of streams or pick specific ones.
Tip: The stream can be found more easily by typing its name.
If you don’t see a stream you were expecting to find, please check if your access key has the required scope. If that’s not the issue, then it’s probably because we still haven’t implemented it. Feel free to get in touch and request it!
Select the streams and click Next.

3. Configure data streams

Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data), and the type of sync.
  • Layer: Choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
  • Folder: A folder can be created inside the selected layer to group all tables being created from this new data source.
  • Table name: We suggest a name, but feel free to customize it. You have the option to add a prefix to all tables at once and make this process faster!
  • Sync Type: You can choose between INCREMENTAL and FULL_TABLE.
    • Incremental: every time the extraction happens, we’ll get only the new data — which is good if, for example, you want to keep every record ever fetched.
    • Full table: every time the extraction happens, we’ll get the current state of the data — which is good if, for example, you don’t want to have deleted data in your catalog.
Once you are done configuring, click Next.

4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters. To define your Trigger, consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times). Optionally, you can define some additional settings:
  • Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource here.
  • Determine when to execute an Additional Full Sync. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while.
Once you are ready, click Next to finalize the setup.

5. Check your new source

You can view your new source on the Sources page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.
For you to be able to see it on your Catalog, you need at least one successful source run.

Troubleshooting

Streams and Fields

Available streams

The table below lists every stream, its slug (the exact identifier to pass when creating the source via API) and a short description. Streams marked optional are only discovered when the corresponding setting is enabled.

Fields by stream

Below you’ll find all available data streams from Bitrix24 and their main fields. CRM entity streams (contacts, companies, deals, leads, activities, product) have schemas built dynamically from the Bitrix API, so custom fields (e.g. UF_*) may vary per portal.
Stream for CRM activities (calls, meetings, tasks, etc.). Schema is built from the Bitrix API.Key fields:
Metadata stream for activity field definitions (types, labels, options).Key fields:
Stream for telephony (Voximplant) call statistics. Requires scope telephony.Key fields:
Stream for CRM companies. Schema is built from the Bitrix API.Key fields:
Metadata stream for company field definitions.Key fields:
Stream for CRM contacts. Schema is built from the Bitrix API.Key fields:
Metadata stream for contact field definitions.Key fields:
Stream for deal categories (pipelines/funnels). Schema is built from the Bitrix API.Key fields:
Stream for comments attached to deals. Available only when “Enable deal comments stream” is turned on. One API call per deal.Key fields:
Metadata stream for deal field definitions.Key fields:
Stream for products (line items) linked to deals. Available only when “Enable deal products stream” is turned on. One API call per deal.Key fields:
Stream for CRM deals. Schema is built from the Bitrix API. Optionally can include CONTACT_IDS per deal when “Extract deal contacts” is enabled.Key fields:
Stream for deal stage (pipeline step) change history.Key fields:
Stream for company structure (departments). Requires scope departments.Key fields:
Metadata stream for lead field definitions.Key fields:
Stream for CRM leads. Schema is built from the Bitrix API.Key fields:
Stream for lead stage change history.Key fields:
Stream for Open Lines (communication channels) configuration. Requires scope imopenlines.Key fields:
Stream for CRM product catalog. Schema is built from the Bitrix API.Key fields:
Metadata stream for product field definitions.Key fields:
Stream for CRM quotes. Schema is built from the Bitrix API. Supports incremental sync using the DATE_MODIFY replication key.Key fields:
Metadata stream for quote field definitions.Key fields:
Stream for products (line items) linked to quotes. Available only when “Enable quote products stream” is turned on. One API call per quote.Key fields:
Stream for SPA (Smart Process Automation) entity types. Used to discover dynamic SPA streams.Key fields:
Dynamic streams created per SPA entity type in your Bitrix portal (e.g. spa_128, spa_fields_128). Data and field metadata for each SPA entity type; structure depends on your Bitrix configuration.
Stream for CRM status list (e.g. deal/lead status options).Key fields:
Stream for Bitrix24 users. Requires scopes user, user_brief, user_basic.Key fields:
Stream containing the stage history records for Smart Process Automations (SPAs). Incremental sync is supported using CREATED_TIME.Key fields:

Data Model

The following diagram illustrates the relationships between the core data streams in Bitrix24. CRM entities relate as follows: Contacts and Companies are standalone; Deals and Leads can be linked to contacts and companies. Deals are organized by Deal Categories (funnels/pipelines). Activities can be attached to deals, contacts, and other entities. product is the catalog; deal_products links products to deals. Users and departments describe your organization; calls and open_lines are telephony and communication data. Field streams (*_fields) describe the schema of their entity (contact, company, deal, lead, activity, product, SPA).

BI Connector streams

Below you’ll find the specific data streams available when using the BI Connector in Bitrix24 (ensure Enable BI reports is turned on). The connector also fetches standard CRM and organizational streams via the outbound webhook (documented above).
Open Channels dialog statistics from the Bitrix24 BI Connector. It exposes one row per Open Channels session (dialog) with pre-computed SLA metrics: response times, dialog duration, timestamps, operator, channel and status.

Implementation Notes

  • Optional streams: deal_comments and deal_products appear only when enabled in the source configuration and add one API call per deal; quote_products appears only when enabled and adds one API call per quote. Use only if needed.
  • Deal filtering: Use “Filter deal category IDs” to sync only specific funnels and reduce volume.
  • Rate limits: If Bitrix returns high “operating time” values, the tap pauses automatically; you can adjust “Operating time threshold” if needed.
  • SPA streams: spa_types is synced first; then one spa_{id} and one spa_fields_{id} stream per SPA entity type in your portal.
  • Connection resilience: Schema discovery includes connection pooling and an automatic retry mechanism with exponential backoff (up to 5 attempts). This improves stability when dealing with temporary network issues or API timeouts during the initialization phase.
  • SPA custom field collisions: Bitrix24 Smart Process Automations can return custom fields whose codes differ only by letter case (e.g., ufCrm10FotoPrincipal vs ufCrm10Fotoprincipal). To avoid data collapsing into a single column, the connector preserves the original column names exactly as returned by Bitrix and automatically resolves collisions by appending a numeric suffix (e.g., _2, _3) to the overlapping fields. If you need to enforce a specific mapping without changing your Bitrix24 setup, pin the names using the SPA Column Name Overrides setting.

BI Connector Replication & Data Quirks

When utilizing the BI Connector to extract reports like imopenlines_session_stats, be aware of the following behaviors and quirks:
  • Incremental Syncs on DATE_CREATE: The BI dataset has no DATE_MODIFY column, so DATE_CREATE is used as the replication key.
  • Mutable Sessions: A session created today might be answered or closed days/weeks later, which backfills its stats (e.g. TIME_*, DATE_*). The primary key is ID, and downstream merges should perform an upsert. The bi_reports_lookback_days configuration handles re-pulling recent sessions to capture late updates.
  • Timestamps: All timestamps are portal-local (e.g. YYYY-MM-DD HH:MM:SS in the account’s configured timezone) and are landed as-is without timezone conversions.
  • String replication key: Because BI datasets expose naive, portal-local timestamp strings, the replication key is landed unchanged as a string type rather than a timestamp type. The connector safely parses the raw bookmark value internally to calculate the proper lookback windows without causing timestamp validation errors, ensuring reliable incremental syncs for BI reports.
  • Inflated Response Times: Unanswered sessions will show constantly accruing TIME_* metrics while a client waits. Filter on answered status states before computing SLA aggregates.
  • No Operator on Certain Channels: Sessions coming from Facebook or Instagram comments might register an OPERATOR_ID of 0 with a null operator name.

Skills for agents

Download Bitrix24 skills file

Bitrix24 connector documentation as plain markdown, for use in AI agent contexts.