Skip to main content
Insyrge - Zoho CRM & Business Automation Consulting
← Back to All ArticlesEnterprise Systems & CRM

How to Migrate CRM Data via API

When to use a vendor wizard versus a scripted API migration, and how to move records without losing relationships or creating duplicates

•Insyrge

How to migrate CRM data via API: when APIs beat import wizards, how to use upserts and external IDs, the safe record order, and how to validate before cutover.

TL;DR: You migrate CRM data via API when the built-in import wizard cannot preserve relationships, custom objects, or a rerunnable, auditable load. The safe pattern is the same on Zoho, HubSpot or Salesforce: extract a clean source, map fields to API names, load parents before children, upsert on a stable external ID, and turn automation off for the backfill. Vendor wizards are still the right first option when they support your source system. Zoho, for example, can migrate from several CRMs with a wizard or an API transfer, and its Bulk Write API can load up to 25,000 records per CSV job, with documented limits you have to plan around.

Key takeaways

  • Start with the vendor's migration wizard or official transfer if your source is supported. Use a scripted API migration when you need custom transforms, a rerunnable load, or objects the wizard does not handle well.
  • Give every source record a stable external ID in the destination, then upsert rather than insert, so you can rerun the job without creating duplicates.
  • Load in dependency order: users and roles first, then accounts, contacts, deals, products, activities, notes and files.
  • Turn off or bypass workflows, assignment rules and notifications during the backfill. Zoho states that its Bulk Write API does not support workflows.
  • Do not sign off on counts alone. Reconcile each module, then spot-check records with their related notes, activities and owners before you cut over.

A CRM migration is easy to describe and easy to get wrong. Export, map, import, go live. The problems show up when notes are not attached, owners are wrong, duplicates appear on the second run, or a workflow fires a thousand emails mid-load.

This guide is about the API path: when to use it, how to structure the load, and which official limits matter. It sits alongside our broader CRM Migration Services Guide and CRM Migration Challenges: 7 Problems and Fixes. If you are moving specifically from Salesforce to Zoho, we already wrote Salesforce to Zoho CRM Migration Without Data Loss.

Want a migration plan that uses the API safely, with a trial run before anyone switches systems? Contact Insyrge or book a call.

When should you migrate CRM data via API?

Use the official wizard or transfer first if it supports your source. Zoho CRM's data migration overview describes a Data Migration wizard that maps CSV files to modules, and an API transfer for Pipedrive, Capsule, HubSpot, Insightly, Highrise, Bitrix and Bigin, where you provide an API key and the move runs without a manual file map. Salesforce, Dynamics and several other sources have their own guided paths.

Choose a scripted API migration when one or more of these is true:

  • You need transforms the wizard cannot do, such as splitting fields, merging duplicates with your own rules, or rebuilding parent-child links from source IDs.
  • You must be able to rerun the load after a failed batch, a mapping fix or a delayed delta.
  • You need objects, files or history the wizard skips or handles poorly.
  • You are moving into a system whose vendor transfer is not available for your source, or you are writing into more than one destination.

An API migration is not automatically safer. It is only safer when you design it to be idempotent, ordered and checked. A one-off script that inserts records by name will create a mess on the second run.

What does a safe API migration look like?

The shape is the same whether the destination is Zoho, HubSpot, Salesforce or another CRM.

  • Inventory the source. List objects, record counts, required fields, files, custom objects and automations that must stay quiet during the load.
  • Clean before you move. Deduplicate and drop records you have already decided not to keep. Do not use the migration to postpone that decision.
  • Map to API names, not labels. Labels change. API names are what the endpoints expect.
  • Store the source ID in a unique custom field on the destination record. That is your join key for children, for validation and for every rerun.
  • Upsert, do not blind-insert. Zoho CRM upsert records API inserts a record or updates it when a duplicate-check field matches, including a user-defined unique field. Other CRMs have the same idea under names like upsert, external ID or dedupe key.
  • Load parents before children. Users and roles, then accounts, then contacts, then deals, then products and price books, then activities, notes and, last, files.
  • Validate after each stage before you start the next one.

HubSpot's practical overview of CRM data migration describes a similar sequence: assess, cleanse, map, test in a sandbox, migrate, validate, cut over, then a short period of close support. We follow that order in our own work, with at least one full trial load into a sandbox or test org before production.

Which official API limits should you plan for?

Plan the job around documented limits, not around a laptop that "seemed fine on a sample."

On Zoho CRM, Zoho CRM Bulk Write API limitations states that the Bulk Write API is asynchronous, accepts a zipped CSV, and that a CSV file can contain a maximum of 25,000 records with 200 column headers, with a 25 MB size limit for modules such as Leads, Contacts and custom modules. A single bulk write job uses 500 API credits, regardless of its state. The API does not support attachments, notes, file upload fields or record images, and it does not support workflows. Lookups need a specific column header, such as Account_Name.id when you already have the related record's ID.

That last point is why source IDs matter. If Bulk Write will not load notes and attachments, those have to move through other APIs after the parent records exist.

Zoho's wizard has its own file limits, also in the Zoho CRM's data migration overview: CSV only, 5 GB per file, up to 200 files and 25 GB in total, with no folders inside the zip. Users should be migrated first, and owner IDs mapped, so ownership is not invented at import time. Checkbox values need to be True or False, and picklist values must already exist in Zoho.

On Salesforce, large loads belong on the Salesforce Bulk API documentation rather than on one-record SOAP or REST calls. On HubSpot, the CRM APIs return JSON and paginate with an after cursor, and exports have their own endpoints. In every case, read the current official limit page for your edition before you schedule the cutover. Credits, daily caps and concurrency change by plan.

How do you keep the load from breaking the live system?

  • Run the first full pass in a sandbox.
  • Disable or bypass workflows, assignment rules, duplicate alerts and marketing emails for the migration user or during the load window. Zoho's Bulk Write will not fire workflows, but other APIs and other CRMs will.
  • Respect rate limits. Queue work, retry only what is safe to retry, and park failures for review instead of tight-looping.
  • Keep the source system read-only, or capture a delta, when you do the final cutover, so new records created during the load are not lost.
  • Keep a rollback plan you have actually tested: a source export, a way to identify every record the job wrote, and a decision about how long after go-live a rollback is still possible.

How do you know the migration worked?

Counts are necessary and not sufficient. After each module, we check:

  • Record counts by module, and by owner where that is meaningful, against the source extract.
  • A sample of records opened with their contacts, deals, notes, activities and files attached.
  • Dates and owners preserved, not reset to the migration date or the integration user, unless you have chosen that on purpose.
  • Picklists and required fields populated, with no silent blanks where the source had a value.
  • A handful of reports or views the business actually uses, to see whether totals still make sense.

Only then do you cut over, turn automations back on, and watch the first days of live work. If you also need help with the wider change, not just the load, see How Risky Is It for a 40-Person Company to Migrate CRM?.

Sources

Frequently asked questions

How do you migrate CRM data via API?

Export and clean the source, map fields to API names, store each source ID in the destination, then upsert records in dependency order: users, accounts, contacts, deals, activities, notes and files. Test the full load in a sandbox, keep workflows off during the backfill, and validate counts plus a sample of related records before cutover.

When is an API migration better than a CSV import wizard?

When you need custom transforms, a job you can rerun without duplicates, or objects the wizard does not handle well, such as complex relationships or a follow-up delta. If the vendor already offers a supported transfer for your source, start there.

Will Zoho Bulk Write move notes and attachments?

No. Zoho's Bulk Write documentation says the API does not support attachments, notes, file upload fields or record images, and it does not support workflows. Move those records with other APIs after the parent records exist.

How do you avoid duplicates if the API job is run twice?

Write a stable source ID into a unique field in the destination and use upsert (or the equivalent external ID update) so a second run updates the same records instead of inserting new ones.

Should workflows run during an API migration?

Usually no. Assignment rules, notifications and automation can fire thousands of times on a backfill. Zoho's Bulk Write API does not run workflows, but other endpoints will, so disable or bypass them until the load is validated.

Want the migration written as a rerunnable API job, not a one-off import?

Insyrge plans the mapping, writes the load, runs a trial in a sandbox and stays with you through cutover. Contact Insyrge or book a call.

See also: Zoho CRM implementation, HubSpot consulting and ERP and CRM integration.

Related resources

About the Author

Manav Sharma is the founder of Insyrge and a CRM solutions architect. He works across Zoho, Salesforce, HubSpot, Odoo and more, designing the CRM setups, integrations and automations that keep sales and operations teams working from the same data.

Need Help Implementing This in Your Business?

Our certified Zoho consultants and automation experts can help you design and deploy custom workflows tailored to your operations.

Book Free Consultation