Bulk API 2.0 for Salesforce: A Practitioner's Field Guide

The Salesforce Bulk API 2.0 is the tool you reach for when the standard API is too slow and a CSV is too dangerous. It exists for one reason: to move large volumes of records into or out of Salesforce asynchronously, without holding a connection open or hammering governor limits. If you are migrating, exiting, or archiving at any real scale, you are using it, directly or through a tool that wraps it. Here is how it actually works, and where it bites.

What it does, and what it does not

Bulk API 2.0 moves bytes at volume. You create a job, upload your records as a single CSV, and Salesforce takes over: it splits the data into batches server-side, processes them asynchronously in the background, and produces result files listing every successful and failed record. You poll the job until it completes. That is the whole loop.

What it does not do is transform or validate. It will load whatever you give it. It does not know that your legacy "Amount" column is in cents, that two of your contacts are the same person, or that a required lookup is pointing at nothing. That logic is the migration. Bulk API 2.0 is the freight; the mapping and the gates are the work.

v2 versus v1: let Salesforce do the batching

The original Bulk API made you split data into batches yourself and manage each one. Bulk API 2.0 removed that chore: you submit one dataset and Salesforce handles the chunking. For almost all new work, v2 is the right default. It is simpler, and it lets the platform size batches to current conditions rather than a number you guessed. The main reason to still touch v1 is a specific legacy workflow already built around explicit batch control.

Parallel versus serial, and why locking matters

By default, Bulk API 2.0 processes in parallel, which is fast. But parallelism is also how you create row-lock contention. Load child records that all roll up to the same parent account in parallel, and multiple batches fight for a lock on that one parent. The result is lock errors and retries that can make a parallel load slower than a serial one.

The fix is to control ordering, not just concurrency. Sort the data so records touching the same parent land together, or run in serial mode for the objects where contention is real. This is one of the most common reasons a migration that "worked in the sandbox" falls over on production volume: the sandbox did not have enough records to trigger the locking.

PK chunking for extraction at scale

Pulling millions of records out of Salesforce has its own wall: a query that would time out. Primary-key chunking is the answer. Instead of one enormous query, you extract in ranges of record IDs, so each slice is a bounded, indexed read. For large exits and warehouse loads, PK chunking is the difference between an extraction that finishes and one that dies at hour three.

Error handling is the whole game

At volume, some records will fail. That is not a defect; it is the point of the results file. The discipline is what you do with it: read the failure file, understand the errors, fix the source or the mapping, and re-run only the failures. A professional migration treats the results file as a work list. An amateur one loads, sees "job complete," and assumes success. "Complete" means the job ran, not that every record landed.

The honest note

Bulk API 2.0 is a genuinely good piece of engineering, and it is table stakes, not a differentiator. Knowing its concurrency modes, its chunking, and its error semantics keeps you out of trouble. But it moves records; it does not make a migration safe. Safe comes from the layer around it: a validated mapping, a dry run against real data, golden datasets pinned for the records you cannot get wrong, and a signed record of what moved. That is where the ETL work and the migration itself actually live.