July 13, 2026
To update or push Salesforce records with the MuleSoft Salesforce Connector, use one of three write operations: Create to insert new records, Update to change existing ones by their record ID, and Upsert to insert-or-update by an external ID. For pushing data from another system, Upsert with an external ID is the safest choice because it never creates duplicates. Each operation takes an array of records mapped with DataWeave and returns a per-record success or error result.
This guide shows how to update and push records step by step, when to use each operation, how to handle bulk writes, and how to fix the errors that show up most — the write side of any MuleSoft and Salesforce integration.
Pushing records means writing data from an external system into Salesforce through the MuleSoft Salesforce Connector - creating new records or updating existing ones so Salesforce stays current with the source. It's the write half of an integration; the read half is querying data out.
In a typical flow, a Mule application receives data - an order from an ERP, a lead from a form, a status from an ops platform - maps it to Salesforce fields, and calls a write operation. The connector handles the API call, and the response tells you which records succeeded and which failed.
Before it writes anything, the connector authenticates to Salesforce - OAuth 2.0 (JWT bearer for production) or Basic auth for testing. For the exact inputs each write operation expects, keep the connector's operations reference and documentation open as you build.
Choosing the right operation prevents duplicates and failed writes. Here's the quick decision guide.
OperationWhat it needsUse whenCreateField values (no ID)The record is brand new to SalesforceUpdateThe Salesforce record IDYou already know the record existsUpsertAn external ID fieldPushing from another system without duplicates
The rule of thumb: if the data comes from an external system and you can't be sure whether the record already exists, use Upsert with an external ID. It's the one operation that safely handles both new and existing records in a single call.
Update changes existing records, matched by their Salesforce ID. Here's the flow.
Id.Id plus the fields to change, using Salesforce API field names.success is true and log any errors.Update fails if an ID is missing or wrong, so validate that every record carries a valid Id before the call.
Upsert is the workhorse for pushing data in from another system. It uses an external ID field - a custom field on the Salesforce object marked "External ID" that holds the unique key from the source system.
Source_Record_Id__c) and mark it as an External ID.This is why Upsert is the default for pushing records — one call keeps Salesforce in sync with the source, whether the record is new or not.
The standard operations work record by record, which is fine for small volumes but burns API calls fast. For hundreds of thousands of records, switch to the connector's Bulk operations, which use the Salesforce Bulk API to process data asynchronously in batches.
The trade-off is timing: bulk is asynchronous, so results come back after the job finishes rather than instantly. For live, single-record pushes, stay with the standard operations. Bulk behavior can shift between connector releases, so pin your connector version (the Mule 4 line) and check the release notes before upgrading.
Write operations fail for a predictable set of reasons. Here's how to clear the common ones.
ErrorRoot causeFixMALFORMED_IDMissing or invalid record ID on UpdateEnsure every record carries a valid 15- or 18-character IDDUPLICATE_VALUEDuplicate rule or a repeated unique fieldUse Upsert on an external ID; dedupe before writingREQUIRED_FIELD_MISSINGA required Salesforce field wasn't sentAdd the field in the DataWeave mappingINVALID_FIELD / picklist errorWrong API name, type, or picklist valueMatch API field names and align picklist valuesField-level security errorIntegration user can't edit the fieldGrant field access on the integration user's profile
Because the connector returns results per record, a batch can partly succeed - always inspect each result rather than assuming the whole call worked. For platform detail, the Salesforce Developer blog and Salesforce Admins resources cover write errors and limits, and Apex Hours and Salesforce Ben have MuleSoft examples.
A few habits keep your writes clean, idempotent, and inside Salesforce limits:
These are the same standards we hold on every Salesforce integration with MuleSoft, because a write that fails quietly is worse than one that fails loudly.
Use the connector's Update operation. Supply each record's Salesforce ID plus the fields to change, mapped with DataWeave, then call Update on the target object. Check the per-record result to confirm each write succeeded.
Update changes existing records matched by Salesforce ID and fails if the record doesn't exist. Upsert matches on an external ID and creates the record if it's missing or updates it if it exists - which is safer for pushing data from another system.
Use Upsert with an external ID field that holds the unique key from your source system. Salesforce matches on that field and updates the existing record instead of creating a new one, so repeated pushes stay idempotent.
Use the Bulk operations, which run on the Salesforce Bulk API and process records asynchronously in batches. Batch within Salesforce limits, then read the job results to catch any failed rows.
Salesforce write operations return a result per record, so a batch can partially succeed. Inspect each result, log the failures with their error messages, and retry or correct those rows rather than assuming the whole call worked.
Yes - "SFDC" is shorthand for Salesforce, so the MuleSoft SFDC connector is the same Anypoint Connector used here to update and push records. The Create, Update, and Upsert operations work the same regardless of which name you see.
Through the Salesforce connection you configure once - OAuth 2.0 (JWT bearer for production) or Basic authentication with a username, password, and security token for testing. That connection is reused across every write operation in your flows.
Updating and pushing Salesforce records with the MuleSoft Salesforce Connector comes down to picking the right operation - Create, Update, or Upsert - mapping fields cleanly, handling partial failures, and using Bulk for volume. Get those right and data flows into Salesforce accurately, every run, without duplicates.
That's what we do at Minuscule Technologies. As a trusted Salesforce engineering partner with 160+ specialists and 75+ projects delivered since 2014, we design and build Salesforce integrations and MuleSoft-based data flows for enterprises - including Nasdaq-listed firms - that need clean, reliable writes into Salesforce from every system they run. From a single push flow to an API-led integration program, we build it and manage it long term.
Need Salesforce records to update themselves from the rest of your stack? Talk to Minuscule Technologies and let's build the flow.
You've seen what's possible. Now, let's make it happen for your business. Whether you need an end-to-end Salesforce solution, a complex integration, or ongoing managed services, our team is ready to deliver.
Schedule a Free Strategic Call
