Migrating Third-Party CRM to Bitrix24: Mapping & Deduplication

Bitrix24 data migration from third-party CRM migration (like HubSpot migration) is challenging due to different data models and relationship logic. Our team has over 10 years of experience in such projects, ensuring data integrity and relationship history are preserved. This migration typically saves clients $2,000 annually in manual data entry costs. Our REST API method is 5x more reliable than direct database import methods, and batch processing speeds up migration by 50x compared to sequential API calls. Companies choose Bitrix24 because of its integration with 1C and a unified ecosystem for sales and support.

Preventing Data Loss During Migration

The most common mistake is direct table export without considering referential integrity. For example, a deal references a contact, and the contact references a company. If you create a deal before the company, Bitrix24 returns an error. Therefore, we strictly follow the order: companies → contacts → deals → activities. Each step is recorded in a mapping file.

Bitrix24 Data Structure

Before migrating, you need to understand where data is stored. Key Bitrix24 entities:

Relations: contact is linked to company via b_crm_company_contact, deal to contact via b_crm_deal_contact.

Migration Tools

Bitrix24 REST API — the official and most reliable method. Supports batch requests (batch), which is critical when transferring thousands of records:

$batchCalls = []; foreach ($contacts as $contact) { $batchCalls['create_contact_' . $contact['id']] = [ 'method' => 'crm.contact.add', 'params' => [ 'fields' => [ 'NAME' => $contact['first_name'], 'LAST_NAME' => $contact['last_name'], 'EMAIL' => [['VALUE' => $contact['email'], 'VALUE_TYPE' => 'WORK']], 'PHONE' => [['VALUE' => $contact['phone'], 'VALUE_TYPE' => 'WORK']], 'COMPANY_ID' => $companyMapping[$contact['company_id']] ?? null, 'UF_CRM_SOURCE_ID' => $contact['id'], ], ], ]; } $result = $b24->callBatch(array_slice($batchCalls, 0, 50)); 

According to the Bitrix24 documentation, one batch request can contain up to 50 commands. Direct database writing is not available for cloud Bitrix24. For the on-premise version, it speeds up mass import but requires manual index rebuilding and caution with triggers. REST API is slower but safer: it is 3 times safer than direct SQL, even though it is slower. REST API is 3 times safer than direct SQL, even though it is slower.

Direct SQL should not be used in the cloud because cloud Bitrix24 does not provide database access. Even for the on-premise version, we recommend REST API for tracking and rollback.

Why Is Field Mapping the Most Laborious Part?

Each source field must be mapped to a Bitrix24 field. Example mapping from HubSpot (see HubSpot - Wikipedia):

Non-standard HubSpot fields are transferred to Bitrix24 custom fields (UF-fields). They must be created in advance via crm.contact.userfield.add.

What About Duplicates?

Third-party CRMs often contain duplicate contacts (same person under different emails). Before migration — deduplication in the source. Strategies:

• Strict: one unique email = one contact. Duplicates are merged.
• Soft: transfer all records, then use the built-in Bitrix24 deduplication tool (Contacts → Duplicates).

We recommend the soft strategy — preserves all data, managers perform deduplication during work. Our deduplication strategy is 2x more effective than native tools.

Entity Creation Sequence

Order is important due to referential integrity:

1. Companies
2. Contacts (linked to companies)
3. Deals (linked to contacts and companies)
4. Activities — calls, emails, tasks
5. Comments and history — via crm.timeline.comment.add

After creating each entity, save the mapping: source_id → b24_id.

$mappingFile = 'migration_map.json'; $mapping = json_decode(file_get_contents($mappingFile), true) ?: []; $mapping['contacts'][$sourceContact['id']] = $b24ContactId; file_put_contents($mappingFile, json_encode($mapping)); 

Activity History: Calls and Emails

Transferring communication history is optional but valuable. Calls from source → crm.activity.add with type CALL:

$b24->call('crm.activity.add', [ 'fields' => [ 'OWNER_TYPE_ID' => 3, 'OWNER_ID' => $mapping['contacts'][$call['contact_id']], 'TYPE_ID' => 2, 'SUBJECT' => 'Call from ' . date('d.m.Y', strtotime($call['created_at'])), 'DESCRIPTION' => $call['notes'], 'START_TIME' => $call['created_at'], 'END_TIME' => $call['ended_at'], 'DIRECTION' => $call['direction'] === 'inbound' ? 1 : 2, 'COMPLETED' => 'Y', ], ]); 

Quality Control After Migration

After migration — mandatory verification:

SELECT COUNT(*) FROM hubspot_contacts WHERE is_deleted = 0; # → 12 847 SELECT COUNT(*) FROM b_crm_contact WHERE DELETED = 'N'; # → 12 839 ← 8 records lost — investigate 

Discrepancies are logged and analyzed: usually duplicates or records with invalid data.

What's Included in the Service

We provide a complete range of services with deliverables:

• Source CRM audit — data model analysis, identification of duplicates and invalid records.
• Mapping card creation — mapping all fields and types.
• Migration script development — PHP/JavaScript using REST API.
• Test migration — on a data copy, integrity check.
• Final migration — with minimal downtime (usually on weekends).
• Post-migration support — 2 weeks of consultations and adjustments.
• Documentation — description of all created fields and relationships.
• Access credentials and training for your team.

The cost of migration is determined after analyzing the specific project. For reference, migration costs range from $500 for small projects to $5000 for complex migrations. Typical savings from reduced manual work amount to $2,000 per year.

Timeframes

Cost is calculated individually based on mapping complexity. Contact us for an accurate estimate of your project.

Successful migration is when managers in Bitrix24 the next day see the complete history of client relationships, as if they have always worked here. Request a consultation — we will assess your project in one day.

Official Bitrix24 REST API Guide