Composite API Patterns

Composite API Patterns

Use this skill when an integration needs to group multiple Salesforce REST API operations into a single HTTP round trip. The Composite family of resources — /composite/, /composite/sobjects/, /composite/tree/, and /composite/batch/ — each serve distinct use cases and carry distinct limits. Choosing the wrong resource wastes API calls, violates atomicity requirements, or silently drops errors.

This skill focuses on the four Composite resources, their request/response shapes, limit boundaries, dependency management via referenceId, and the allOrNone flag behavior. It does not cover single-resource REST CRUD, SOQL pagination, Bulk API 2.0, or GraphQL.

Before Starting

Gather this context before working on anything in this domain:

• What Salesforce API version is in use? Spring '25 = v63.0. Always pin the version in all endpoint URLs.
• Do any subrequests depend on results from earlier subrequests? If yes, only /composite/ supports cross-subrequest referenceId resolution. /composite/batch/ does not.
• How many records are involved? /composite/ and /composite/batch/ each support up to 25 subrequests. /composite/sobjects/ supports up to 200 records per call. /composite/tree/ supports up to 200 records across up to 5 nesting levels.
• Is atomicity required? /composite/ with allOrNone: true and /composite/tree/ are always atomic. /composite/ with allOrNone: false and /composite/batch/ allow partial success and require per-subrequest response inspection.
• What is the DML budget? Governor limits still apply per subrequest. 25 subrequests each touching 200 records = 5,000 DML rows — this can hit org limits. Composite counts as one API call total toward the daily limit.

Core Concepts

The Four Composite Resources

Salesforce exposes four distinct resources under the /composite/ path. They are not interchangeable.

/composite/ — Ordered, dependent subrequests

POST /services/data/v63.0/composite

Executes up to 25 subrequests in sequence within a single HTTP call. The key differentiator: results from earlier subrequests can be referenced in later subrequests using @{referenceId.fieldName} syntax. Salesforce resolves references server-side before executing the dependent subrequest. Supports allOrNone: true (atomic rollback on any failure) or allOrNone: false (partial success, each result independent).

/composite/sobjects/ — Bulk CRUD on same-type records

POST   /services/data/v63.0/composite/sobjects          (create up to 200)
PATCH  /services/data/v63.0/composite/sobjects          (update up to 200)
DELETE /services/data/v63.0/composite/sobjects?ids=...  (delete up to 200)
GET    /services/data/v63.0/composite/sobjects?ids=...  (read up to 2000)

The sObject Collection resource processes up to 200 records of a uniform type in a single call. Records are not required to be the same object type for reads, but DML operations (create, update, delete) require uniform type. Supports allOrNone flag. No cross-record referencing.

/composite/tree/{SObject}/ — Hierarchical parent-child inserts

POST /services/data/v63.0/composite/tree/Account/

Inserts a parent record with its related child records in one atomic call. Up to 200 total records across up to 5 nesting levels. Always atomic — no partial success. All records in the tree use temporary referenceId labels for response correlation, but child records reference parents via the attributes.referenceId + nested structure, not the @{} syntax used in /composite/.

/composite/batch/ — Bundled independent subrequests

POST /services/data/v63.0/composite/batch

Executes up to 25 subrequests that cannot reference each other. Each subrequest is a complete, standalone REST call. Results are independent. The haltOnError flag stops processing on the first failure but does not roll back completed subrequests. Use when you want to reduce round trips for logically unrelated operations.

referenceId and Cross-Subrequest Dependency

In /composite/ requests, each subrequest carries a referenceId string. Later subrequests in the same call can embed @{referenceId.fieldPath} anywhere in their request body or URL. Field paths follow dot notation for nested fields.

"body": {
  "AccountId": "@{NewAccount.id}"
}

referenceId values are case-sensitive. A typo in the reference token causes the subrequest to receive a literal string rather than the resolved value, which typically results in a validation error that is reported in the per-subrequest response body — not in the outer HTTP status.

References can also appear in URL segments for GET subrequests:

"url": "/services/data/v63.0/sobjects/Contact/@{NewContact.id}"

allOrNone Flag and Error Behavior

The allOrNone flag controls atomicity:

• allOrNone: true — If any subrequest fails, all subrequests in the call are rolled back. The response still returns HTTP 200. Failed subrequests report their error in the per-subrequest body with an HTTP status code in the httpStatusCode field. Successful subrequests that were rolled back show httpStatusCode: 400 with PROCESSING_HALTED errorCode.
• allOrNone: false — Each subrequest executes independently. A failure in one does not affect others. You must inspect every subrequest response in compositeResponse[] to determine which succeeded and which failed. The outer HTTP response is always 200.

For /composite/tree/, atomicity is always enforced — there is no allOrNone option. One invalid record rolls back the entire tree.

Governor Limits and API Call Accounting

The entire Composite request counts as one API call toward the org's daily REST API limit. However, each subrequest's DML operations count individually against DML governor limits and row limits. Key limits to track:

• 25 subrequests maximum per /composite/ or /composite/batch/ call
• 200 records maximum per /composite/sobjects/ DML call
• 200 total records maximum per /composite/tree/ call, up to 5 levels deep
• Per-transaction DML row limit (150 statements) still applies cumulatively across subrequests
• CPU time and heap limits still apply per subrequest
• Callouts within subrequests are not permitted (Apex trigger callouts from subrequest-triggered DML follow normal Apex rules)

Common Patterns

Pattern 1: Create Account + Related Records in One Atomic Call

When to use: You need to create a parent Account and one or more child Contacts and/or Opportunities in a single transaction without knowing the Account ID in advance and without separate round trips.

How it works: Use /composite/ with allOrNone: true. Assign a referenceId to the Account subrequest and reference @{refId.id} in each child subrequest's relationship field. Order subrequests so the parent appears before any child that references it.

{
  "allOrNone": true,
  "compositeRequest": [
    {
      "method": "POST",
      "url": "/services/data/v63.0/sobjects/Account/",
      "referenceId": "NewAccount",
      "body": { "Name": "Acme Corp" }
    },
    {
      "method": "POST",
      "url": "/services/data/v63.0/sobjects/Contact/",
      "referenceId": "NewContact",
      "body": {
        "LastName": "Smith",
        "FirstName": "Jane",
        "AccountId": "@{NewAccount.id}"
      }
    },
    {
      "method": "POST",
      "url": "/services/data/v63.0/sobjects/Opportunity/",
      "referenceId": "NewOpportunity",
      "body": {
        "Name": "Acme Corp — Q3 Deal",
        "AccountId": "@{NewAccount.id}",
        "StageName": "Prospecting",
        "CloseDate": "2025-12-31"
      }
    }
  ]
}

Why not the alternative: Three separate REST calls require the caller to store the Account ID between calls, manage partial failure compensation (Account inserted, Opportunity failed — now you have an orphaned Account), and make three HTTP round trips. The composite approach is atomic and uses one API call.

Pattern 2: Bulk Upsert Same-Type Records

When to use: An external system sends a batch of 200 or fewer records of the same object type that need to be created or updated in Salesforce. Record volume is too large for individual calls but too small to warrant Bulk API 2.0 async job overhead.

How it works: Use /composite/sobjects/ with a PATCH request and an externalIdFieldName for upsert semantics. All records in the request body go into records[]. Set allOrNone: false to allow partial success, then inspect per-record results.

PATCH /services/data/v63.0/composite/sobjects/Contact/External_Id__c
{
  "allOrNone": false,
  "records": [
    {
      "attributes": { "type": "Contact" },
      "External_Id__c": "EXT-001",
      "LastName": "Adams",
      "Email": "adams@example.com"
    },
    {
      "attributes": { "type": "Contact" },
      "External_Id__c": "EXT-002",
      "LastName": "Brown",
      "Email": "brown@example.com"
    }
  ]
}

Why not the alternative: Individual upsert calls against /sobjects/{SObject}/{ExternalIdField}/{value} for 150 records = 150 HTTP round trips and 150 API calls against the daily limit. The sObject Collection reduces this to 1 API call and 1 round trip.

Pattern 3: Hierarchical Account-Contact Tree Insert

When to use: You need to insert a set of Accounts each with their own Contacts, and the parent Account IDs are not known in advance. The total record count is 200 or fewer and the tree is 5 levels or fewer deep.

How it works: Use /composite/tree/Account/. Each Account in the records[] array can include a Contacts key whose records[] hold the child Contact objects. Assign a referenceId to each record for response correlation.

POST /services/data/v63.0/composite/tree/Account/
{
  "records": [
    {
      "attributes": { "type": "Account", "referenceId": "AcctRef1" },
      "Name": "Globex Corp",
      "Contacts": {
        "records": [
          {
            "attributes": { "type": "Contact", "referenceId": "ContRef1" },
            "LastName": "Simpson",
            "FirstName": "Homer"
          }
        ]
      }
    }
  ]
}

Why not the alternative: Using /composite/ with multiple parent-then-child subrequests is limited to 25 subrequests total. sObject Tree supports up to 200 records across the entire hierarchy in one call, with a cleaner request shape for deeply nested trees.

Decision Guidance

Recommended Workflow

1. Clarify the dependency structure — Determine whether any subrequest needs a result (typically an ID) from a preceding subrequest. If yes, only /composite/ supports this via @{referenceId.field}.
2. Select the correct Composite resource — Apply the Decision Guidance table above. Confirm record count and nesting depth are within resource limits.
3. Design the atomicity strategy — Choose allOrNone: true for all-or-nothing transactions, or allOrNone: false and build per-subrequest error handling into the caller.
4. Build and validate the request body — Confirm all referenceId values are unique, case-correct, and referenced before they are needed. Verify all record types, required fields, and field API names.
5. Implement response parsing — Do not rely on the outer HTTP status. Always iterate compositeResponse[] or per-record result arrays and inspect each httpStatusCode.
6. Assess governor impact — Calculate DML rows, CPU time, and API call count. Confirm the pattern fits within org limits before testing at scale.
7. Run the checker script — Execute scripts/check_composite_api.py against integration files to catch common structural issues before code review.

Review Checklist

Run through these before marking work in this area complete:

• Correct Composite resource is used for the dependency and volume profile (composite / sobjects / tree / batch).
• All referenceId values are unique within the request and case matches their @{} references exactly.
• allOrNone flag is explicitly set; its atomicity implications are documented in the integration design.
• Response parsing inspects every subrequest's httpStatusCode, not just the outer HTTP 200.
• DML row count is estimated (subrequests × records per subrequest) and confirmed within org limits.
• Record count per call does not exceed resource limits (25 subrequests for composite/batch; 200 records for sobjects/tree).
• API version is pinned to v60.0+ in all endpoint URLs.
• Partial failure path is handled when allOrNone: false: caller identifies failed subrequests and acts (retry, DLQ, alert).

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. Outer HTTP 200 does not mean success — All four Composite resources return HTTP 200 on the outer response even when individual subrequests or records fail. Any integration that checks only the outer status code silently discards errors. Always parse compositeResponse[].httpStatusCode or per-record result arrays.

2. referenceId is case-sensitive — If a subrequest sets "referenceId": "NewAccount" but a later subrequest references @{newaccount.id} (lowercase), Salesforce does not resolve the reference. The literal string @{newaccount.id} is passed as the field value, which then fails validation with a confusing error message.

3. allOrNone: true rolls back ALL subrequests, including successful ones — When any single subrequest fails with allOrNone: true, Salesforce rolls back every subrequest in the call, including those that had already succeeded. Rolled-back subrequests report httpStatusCode: 400 and errorCode: PROCESSING_HALTED in their individual response — not a 2xx. This can be misread as a failure of those subrequests rather than a rollback.

4. DML governor limits are not waived per subrequest — 25 composite subrequests, each triggering 200 DML rows, equals 5,000 DML rows in a single transaction. Org-wide DML row limits (150 DML statements, unlimited rows but SOQL and CPU caps) can still be hit. Apex triggers, validation rules, and workflow rules fired by composite subrequests count against the same governor limits as any other transaction.

5. sObject Tree is always atomic — partial success is not available — Unlike /composite/ with allOrNone: false, the tree resource has no partial-success mode. One invalid record in a 200-record tree rolls back the entire payload. Validate records client-side (required fields, field lengths, relationship IDs) before sending large trees.

Output Artifacts

Related Skills

• integration/rest-api-patterns — use for single-resource REST CRUD, SOQL pagination, OAuth Bearer token setup, and overall REST API decision-making.
• data/bulk-api-and-large-data-loads — use when record volumes exceed 200 per operation and Bulk API 2.0 async job patterns are needed.
• integration/oauth-flows-and-connected-apps — use when the authentication setup, Connected App scoping, or token refresh is the actual blocker.
• apex/apex-rest-services — use when a custom REST endpoint must be exposed from the org, not consumed.