Overview
Salesforce REST API Composite Resources are a set of REST endpoints that let you execute multiple operations in a single HTTP request. They reduce network round-trips, lower API request usage, and—depending on the resource—allow you to reference results between subrequests or execute the operations transactionally.
Why use Composite Resources?
Composite Resources are ideal when you need to perform multiple related operations (create/update/delete/fetch) without incurring the latency of multiple API calls. Use them to:
– Reduce client-server round-trips and improve performance.
– Keep related record changes together and optionally enforce transactional semantics (all-or-none).
– Link subrequests by referencing IDs returned earlier in the same composite payload.
Key Composite endpoints
The most commonly used Composite REST endpoints are:
/composite — Execute a series of subrequests in one call. Subrequests can reference results of previous subrequests using referenceId. Useful for mixed operations (different object types).
/composite/batch — Send up to multiple independent subrequests in one request. Subrequests do not reference each other and are executed independently (no inter-request references).
/composite/tree/sObjectName — Create multiple records in a single request using a hierarchical (tree) JSON. Excellent for inserting a parent record with many children in one call.
/composite/sobjects — Perform bulk create, update or delete operations on multiple records of the same sObject in one request.
Example: Composite request with interdependent subrequests
This example creates an Account and a Contact and references the newly created Account in the Contact creation using referenceId and @{...} notation.
POST /services/data/v58.0/composite
{
"allOrNone" : true,
"compositeRequest" : [
{
"method" : "POST",
"url" : "/services/data/v58.0/sobjects/Account",
"referenceId" : "refAccount",
"body" : {
"Name" : "Acme Corp"
}
},
{
"method" : "POST",
"url" : "/services/data/v58.0/sobjects/Contact",
"referenceId" : "refContact",
"body" : {
"FirstName" : "Jane",
"LastName" : "Doe",
"AccountId" : "@{refAccount.id}"
}
}
]
}
Example: Composite Tree (parent with children)
POST /services/data/v58.0/composite/tree/Account
{
"records" : [
{
"attributes" : { "type" : "Account", "referenceId" : "A1" },
"Name" : "Acme Holdings",
"Contacts" : {
"records" : [
{ "attributes" : { "type" : "Contact", "referenceId" : "C1" }, "FirstName" : "John", "LastName" : "Smith" },
{ "attributes" : { "type" : "Contact", "referenceId" : "C2" }, "FirstName" : "Alice", "LastName" : "Brown" }
]
}
}
]
}
Benefits and trade-offs
Benefits:
– Fewer HTTP requests and lower latency.
– Reduced API call consumption (helpful within API limits).
– Transactional control (for endpoints that support allOrNone).
Trade-offs / Things to watch for:
– Composite requests still count against Salesforce governor limits — e.g., SOQL queries, DML, and CPU usage consumed by subrequests.
– Request size and number of subrequests are limited; check Salesforce documentation for current limits when designing payloads.
– Error handling can be more complex: a single failing subrequest may impact the entire composite depending on allOrNone behavior.
Best practices
– Use referenceId to link dependent operations in a single payload.
– Use allOrNone=true when you must guarantee transactional behavior (all succeed or all fail).
– For large-volume single-object operations, use /composite/sobjects or Bulk API when appropriate.
– Always monitor response payloads for partial failures and code robust retry/error handling.
Conclusion
Salesforce REST API Composite Resources are powerful tools to optimize API usage and performance by bundling multiple operations into one HTTP request. Choose the specific composite endpoint based on whether you need inter-request references (use /composite), hierarchical creation (/composite/tree), same-object collections (/composite/sobjects), or independent grouped requests (/composite/batch).