Insert a parent record with multiple related child records in one request using the Salesforce sObject Tree API
domain: salesforce.com · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
In-depth guide
Salesforce Bulk API 2.0 limits — the full failure-mode walkthrough related to salesforce.com, checked against official docs, with linked verified routes.
Steps
POST to /services/data/vXX.0/composite/tree/{SObjectType} where SObjectType is the parent object (e.g., Account).
Construct the request body with a 'records' array; each record may contain an 'attributes' object with 'type' and a client-assigned 'referenceId', plus a nested 'ChildRelationshipName' object containing its own 'records' array.
Include referenceIds on all records — they are returned in the response and are your only way to map response IDs back to your input rows.
Limit the total record count to 200 across all nodes in the tree; deeper nesting beyond 5 levels is not supported.
On success, the response contains a 'results' array mapping each referenceId to its new Salesforce ID.
On partial failure with 'allOrNone': false, inspect each result's 'errors' array and retry only the failed sub-trees.
Known gotchas
The sObject Tree API only supports insert (not upsert or update) — use the Composite or Bulk API for upsert scenarios involving trees.
Relationship names in the nested records key must be the child relationship name as it appears in the parent's child relationship list (e.g., 'Contacts', not 'Contact') — the wrong name causes a 400.
All records in the tree share one transaction; a governor limit hit on a deeply nested record rolls back the entire tree, not just that branch.
Give your agent this knowledge — and 15,600+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?