Prompt
How do I sync contacts between my SaaS app and Salesforce without duplicates?
Latest observation
To sync contacts between your SaaS app and Salesforce without creating duplicates, you need a reliable identity-matching strategy plus a two-way sync design that respects ownership and updates.
1) Pick a stable unique key
Do not use name, email, or phone alone as the identity key if you can avoid it.
Best options:
- Your app’s contact ID stored in Salesforce as a custom field like
External_Contact_ID__c - Or Salesforce’s
Contact.Idstored back in your app after the first sync
Best practice:
- Treat your system as the source of truth for your contact records
- Store the mapping:
app_contact_idsalesforce_contact_id
2) Use upsert, not insert
When syncing from your app to Salesforce:
- Query Salesforce first for an existing contact by external ID
- If found: update
- If not found: create
In Salesforce, use:
- External ID field
- Upsert API
Example flow:
- App contact
12345 - Search Salesforce
External_Contact_ID__c = 12345 - If exists → update that Contact
- If not → create Contact and save returned Salesforce ID
3) Maintain a sync map
Keep a persistent mapping table in your database:
| app_contact_id | salesforce_contact_id | last_synced_at | sync_version |
|---|
This prevents repeated “create” attempts and helps with retries.
4) Match existing Salesforce records before creating
If you’re onboarding existing Salesforce data, do a one-time matching pass using a hierarchy like:
- Exact external ID match
- Exact email match
- Exact phone match
- Fuzzy match on name + company
- Manual review for uncertain matches
Be careful: email can change, and multiple contacts can share the same company/domain.
5) Decide conflict rules
When both systems can edit contacts, define who wins:
- Last write wins
- Salesforce wins for certain fields
- App wins for certain fields
- Field-level ownership (recommended)
Example:
- Salesforce owns: lead status, owner, lifecycle stage
- Your app owns: subscription status, product usage, preferences
6) Prevent duplicate creation with idempotency
For every sync request, make it idempotent:
- Use the app contact ID as the idempotency key
- If a retry happens, the same contact should update the same Salesforce record, not create a new one
7) Handle deletes carefully
Avoid hard deletes in both systems unless you really mean it. Prefer:
- soft delete
- archived status
- sync tombstones
8) Reconcile regularly
Even with good sync logic, drift happens. Run a periodic reconciliation job:
- Find records in Salesforce missing external ID
- Find app contacts missing Salesforce mapping
- Detect duplicates by email/external ID
- Repair or queue for manual review
9) Use Salesforce-native features where possible
Useful tools:
- External ID fields
- Upsert API
- Bulk API for large syncs
- Change Data Capture or Platform Events for near-real-time updates
- Duplicate Rules / Matching Rules in Salesforce to reduce bad inserts
10) Recommended architecture
A solid pattern is:
- Integration service
- Sync mapping table
- Webhook/event listeners
- Upsert to Salesforce
- Periodic reconciliation job
- Conflict-resolution rules
Simple sync algorithm
App → Salesforce
- Receive contact create/update
- Look up mapping by
app_contact_id - If mapping exists, update Salesforce by
salesforce_contact_id - Else upsert by
External_Contact_ID__c - Save mapping
Salesforce → App
- Listen for changes via CDC/webhooks/polling
- Use
salesforce_contact_idto find mapped app contact - If not found, try matching on external ID
- Otherwise create or flag for review
Most important rule
Never create a new Salesforce contact unless you’ve first checked for an existing mapped record or matched on a trusted external ID.
If you want, I can also give you:
- a data model for the sync table
- a Salesforce upsert example
- or a step-by-step sync workflow diagram.
Brands