Using Salesforce Composite API from MuleSoft

Salesforce Composite API is useful when an integration needs to perform several Salesforce REST operations together instead of making a separate network round trip for every step.

A common example is:

create Account
     ↓
use new Account Id
     ↓
create Contact

Without Composite API, MuleSoft might make one Salesforce request, read the returned ID, and then make another request. With the Composite resource, those related subrequests can be sent in one Salesforce REST call.

What Composite API Does

The Salesforce Composite resource executes a series of REST API subrequests in a single request.

A later subrequest can reference output from an earlier one using a referenceId.

Conceptually:

MuleSoft
   │
   └── one HTTP request
          │
          ▼
   Salesforce Composite API
          │
          ├── subrequest 1: create Account
          └── subrequest 2: create Contact using Account Id

Salesforce currently allows up to 25 subrequests in a Composite request, with additional restrictions for query and sObject collection operations.

Example Request

A simplified request body looks like this:

{
  "allOrNone": true,
  "compositeRequest": [
    {
      "method": "POST",
      "url": "/services/data/vXX.X/sobjects/Account",
      "referenceId": "newAccount",
      "body": {
        "Name": "Acme"
      }
    },
    {
      "method": "POST",
      "url": "/services/data/vXX.X/sobjects/Contact",
      "referenceId": "newContact",
      "body": {
        "LastName": "Shah",
        "AccountId": "@{newAccount.id}"
      }
    }
  ]
}

The important part is:

@{newAccount.id}

The second subrequest uses the ID returned by the first subrequest without MuleSoft having to make another round trip in between.

Use the Salesforce API version appropriate for your org and integration rather than copying a hard-coded version from an example.

Calling It from MuleSoft

One straightforward approach is to call the Salesforce REST endpoint through MuleSoft's HTTP Request connector.

The flow can be organized as:

HTTP/API listener
      │
      ▼
DataWeave
build composite request
      │
      ▼
HTTP Request
POST /services/data/vXX.X/composite
      │
      ▼
inspect compositeResponse
      │
      ▼
map result / handle errors

Authentication should use the Salesforce access-token mechanism already established for the integration. Avoid embedding tokens or credentials directly in DataWeave or application configuration files.

Building the Request in DataWeave

For example:

%dw 2.0
output application/json
---
{
    allOrNone: true,
    compositeRequest: [
        {
            method: "POST",
            url: "/services/data/vXX.X/sobjects/Account",
            referenceId: "newAccount",
            body: {
                Name: payload.accountName
            }
        },
        {
            method: "POST",
            url: "/services/data/vXX.X/sobjects/Contact",
            referenceId: "newContact",
            body: {
                LastName: payload.contactLastName,
                AccountId: "@{newAccount.id}"
            }
        }
    ]
}

This keeps request construction separate from transport configuration and makes the dependency between subrequests visible.

`allOrNone` Is a Business Decision

The allOrNone setting controls how Salesforce handles failures across related subrequests.

With:

"allOrNone": true

a failure can cause the composite work to roll back rather than leave earlier successful subrequests committed.

That may be exactly what you want for a tightly coupled business operation.

But it should not be enabled automatically for every composite request. If subrequests are intentionally independent, partial success may be acceptable and should be processed explicitly.

Ask:

Are these subrequests one logical business transaction, or merely several calls grouped for efficiency?

Always Inspect Each Subresponse

A successful HTTP response from the Composite endpoint does not mean every business operation succeeded.

The response contains individual results for the subrequests. MuleSoft should inspect them rather than treating the outer call alone as the success condition.

A useful processing model is:

Composite HTTP response received
        │
        ▼
inspect each subresponse
        │
        ├── expected success → continue
        └── failure → classify and handle

This is especially important when allOrNone is false.

Composite vs Separate Calls

Composite API is attractive when:

operations are closely related;
a later call depends on an earlier result;
reducing network round trips matters;
the workflow fits within Composite API limits;
synchronous processing is appropriate.

Separate calls can be clearer when:

operations have different retry policies;
each step has an independent recovery lifecycle;
a long-running workflow spans multiple systems;
one step should continue even if another dependency is unavailable;
observability and operational control are more important than reducing round trips.

Do not turn a distributed workflow into one huge Composite request merely because the API supports multiple subrequests.

Composite API Is Not Bulk API

Composite API is designed for related synchronous operations, not for replacing large-volume asynchronous ingestion.

If the requirement is to load or extract a very large number of records, Salesforce Bulk API 2.0 is usually the more appropriate family of APIs.

Think of the distinction as:

related synchronous operations → Composite API
large-volume asynchronous data → Bulk API

Composite, Batch, and Tree

Salesforce provides several Composite-family resources.

A useful mental model is:

Requirement	Resource direction
Related REST calls where later calls use earlier results	`composite`
Independent REST calls grouped together	`composite/batch`
Create parent-child record trees	`composite/tree`

Choose based on the shape of the business operation, not simply on which endpoint looks most powerful.

Error Handling in MuleSoft

A production flow should distinguish at least these cases:

transport/authentication failure
Salesforce rate/availability failure
composite-level validation failure
individual subrequest failure
ambiguous timeout after request submission

The last case deserves special attention. If MuleSoft times out after Salesforce may already have processed the request, blindly retrying a create operation can duplicate business effects.

Where possible, use stable business identifiers, External IDs, idempotent target behavior, or reconciliation before replaying ambiguous create operations.

Practical Rule

Use Salesforce Composite API when multiple Salesforce REST operations naturally form one synchronous interaction and benefit from dependency references or reduced round trips.

Do not use it merely to make the Mule flow shorter. The right boundary is the business operation, not the number of connector components on the canvas.