Salesforce REST API Integration Patterns for Data Migration: Composite API, SObject Tree & SOQL

The Composite REST API lets you bundle up to 25 subrequests into a single HTTP POST. Each subrequest can reference the result of a previous one using a referenceId, so you can insert a parent record and immediately pass its new Salesforce ID to a child record, all in one call, no polling required.

Bulk API 2.0 is asynchronous and built for volume, the right choice when loading hundreds of thousands of records. The REST API is synchronous and built for precision: atomic parent-child inserts, hierarchical data loads, pre-migration count queries, and post-migration validation. The two complement each other; neither replaces the other.

When allOrNone is true, the entire Composite request rolls back if any single subrequest fails. You get clean atomic behavior — either everything commits or nothing does. Setting it to false allows partial commits, which can leave orphaned child records in your org that are much harder to track down than a clean failure.

The SObject Tree API is a specialised Composite variant built for relationship hierarchies. You define a root object, say, an Account, with nested child records in a single payload, and Salesforce inserts the entire structure in one call. It supports up to 200 records per request across two nesting levels.

The SObject Tree API supports up to 200 records per request, shared across the root object and all its children combined. It also supports a maximum of two nesting levels. An Account with 150 Contacts consumes 151 of that budget. Plan your batch sizes before the migration window, not during it.

The most reliable approach filters on External_ID__c != null in your COUNT() queries — that way you’re only counting records your migration loaded, not pre-existing data. For relationship integrity, check Contacts where AccountId = null AND External_ID__c != null. Any result above zero means orphaned records to fix before go-live.

The /limits/ endpoint returns your real-time consumption across every Salesforce governor limit — daily API requests remaining, Bulk API batch counts, concurrent request usage, and more. Polling it every 15 to 30 minutes during a long migration window gives you early warning before you exhaust a limit mid-run.

A referenceId is the label you assign to a subrequest in a Composite call. Other subrequests reference its output using the syntax @{referenceId.fieldName}. In practice, this lets you use a newly created Account’s Salesforce ID as the AccountId on a Contact in the same request — no separate query needed.

The key is combining an External ID field with the upsert endpoint. When you include an External_ID__c value on every record and route retries through the upsert endpoint rather than a plain insert, Salesforce matches on that External ID instead of creating a duplicate. This is the standard idempotency pattern for REST API migrations.

Yes, working with the REST API directly requires at least basic development experience. You need to construct HTTP requests, manage Bearer tokens, parse JSON responses, and handle errors. If you don’t have a developer on the project, tools like MuleSoft, Jitterbit, or Data Loader abstract most of this and are more practical options.