Salesforce Upsert with MuleSoft: External IDs, Idempotency, and Duplicate Prevention
Retries are normal in distributed integrations. Duplicate Salesforce records should not be.
For many synchronization flows, upsert with a stable external identifier is safer than implementing "query, then create or update" as separate network operations.
The basic pattern
Assume the source system owns a durable customer identifier CUST-10482, stored in a Salesforce external-ID field such as Source_Customer_Id__c.
source customer
→ DataWeave mapping
→ Salesforce upsert
object: Account
external ID: Source_Customer_Id__c
Conceptually the payload might be:
{
"Source_Customer_Id__c": "CUST-10482",
"Name": "Acme Industries",
"BillingCountry": "US"
}
If a retry delivers the same logical customer again, the external ID gives Salesforce a stable key for finding the existing record.
Why this is better than query-then-create
A flow such as:
query → no record → create
contains a race window. Two concurrent messages can both observe "no record" and both attempt creation. Upsert moves the existence decision into the Salesforce operation designed for that purpose.
MuleSoft's Salesforce Connector reference explicitly notes that in most cases upsert should be preferred over create to avoid unwanted duplicate records.
External ID design matters
An idempotency strategy is only as good as its key. Prefer a source-owned immutable identifier. Avoid names, email addresses, or other mutable business attributes unless the domain truly guarantees their stability and uniqueness.
Upsert is not the whole idempotency story
Upsert protects the Salesforce record identity. It does not automatically make every downstream side effect idempotent. If the same message also sends an email, publishes another event, or updates a second system, those effects need their own duplicate-handling strategy.
Error handling
Separate:
- connectivity/transient failures that may be retried;
- validation or permission failures that need correction;
- duplicate/external-ID data-quality failures that require reconciliation.
Blindly retrying a deterministic validation error only creates noise.