Search documentation...



Push enriched data from your warehouse into Salesforce CRM for your teams to act upon it


With the Salesforce destination, Hightouch can both create and update standard or custom objects, update custom picklist field values on those objects, and create platform events to drive more automation in Salesforce.

Supported syncing

The Salesforce destination supports the following sync types:

  • Object
  • Metadata (Custom Picklists)

Connect to Salesforce

Go to the Destinations overview page and click the Add destination button. Select Salesforce and click Continue. You can then authenticate Hightouch to Salesforce via OAuth. Click Log in to Salesforce, log in with your Salesforce account, and click Allow. You should then see a success notification in the Hightouch UI.

If you have Salesforce Authenticator setup as your 2FA, you may have to accept the request from your device (mobile phone). After you've accepted the request on your device, return to the destination setup page and click Continue*. Give your destination a descriptive name, for example, "Salesforce Production," and click Finish.

Access level recommendations

We recommend that you authenticate with a user that has the correct access to update all fields, records and objects that you need to interact with. Therefore, We highly recommend that you OAuth with a System Administrator or Integration User account.

Syncing data

  • Insert: Insert mode pushes new objects to Salesforce, and doesn't update the objects as they change in your warehouse.
  • Upsert: Upsert mode pushes new objects to Salesforce and updates fields that change in your warehouse.
  • Update: Update mode updates particular fields on existing objects in Salesforce.
  • Archive: Archive mode archives records that are present in the model with Salesforce's archive operation.


Insert is the simplest of modes for pushing to Salesforce. In this mode new objects will be inserted into Salesforce, but future changes to columns of those objects will not be reflected in Salesforce.

This mode is good for the following scenarios:

  • You want to push objects into Salesforce, but don't care if the data within each row remains up to date
  • Static data where each row is never updated, such as events
To ensure syncs send each event, use a hash function for the event model's primary key . The hash should combine all columns, including member ID, timestamp, etc. See the event sync documentation for more information.

Insert has two configuration parameters:

Salesforce Object NameThe name of the object (Account, Contact, etc..) that will be pushed into Salesforce
Hightouch to Salesforce Field MappingsA list of columns that will be pushed to new objects in Salesforce


In this mode, new objects will be inserted into Salesforce and all designated columns will be kept up-to-date within Salesforce.

This mode is good for the following scenarios:

  • You want to push objects into Salesforce and want to keep the data up-to-date

Upsert has three configuration parameters:

Salesforce Object NameThe name of the object (Account, Contact, etc..) that will be updated in Salesforce
Hightouch to Salesforce External Unique Identifier Column MappingThe name of the column on the Hightouch query, and the name of an external ID for the object in Salesforce. Note that this column in Salesforce must be marked as an external ID and unique for this to work.
Hightouch to Salesforce Field MappingsA list of columns that will be pushed to new objects in Salesforce. Each time a sync occurs in Hightouch these columns will be updated.

Hightouch strongly recommends you use an External ID type field as the field to match on for your sync. It should be an explicit External ID type in Salesforce, not just an external ID field by practice.

This lets Hightouch use Salesforce's native upsert API, meaning Hightouch doesn't need to perform a search to determine if a record should be updated or inserted because Salesforce handles the operation. As a result, this improves sync performance and avoids inadvertent duplicates.

You can create a custom field and set it to the External Id type by following the steps outlined in this Salesforce article. Information regarding audit fields in the Salesforce article doesn't apply.

Because inserts are non-idempotent when using Salesforce ID as an identifier, Hightouch doesn't support matching on Salesforce ID when upserting. If you'd like to sync records based on Salesforce ID, use update mode.

Certain Salesforce fields can be set upon row creation but can't be edited on existing rows. Since Salesforce rejects updates to those fields that can't be edited, if you configure a mapping for one, Hightouch omits those mappings during upserts on existing rows, ensuring your sync succeeds. Hightouch still maps and syncs these fields for new rows. To see if a field is editable, check its updateable field property via the Salesforce API.


In this mode, selected columns will be updated for an object within Salesforce. For example, you could add an LTV column to an account or contact. This mode doesn't create new rows for an object within Salesforce. Instead, it updates columns on existing objects.

Update mode requires you to have access to the IDs of the objects you want to update within your warehouse.

This mode is good for the following scenarios:

  • You have objects in Salesforce that you want to add additional information / columns to
  • You want to continuously sync data from your warehouse and add this data to existing objects within Salesforce
  • You already have access to Salesforce object IDs within your warehouse

Update has three configuration parameters:

Salesforce Object NameThe name of the object (Account, Contact, etc..) that will be updated in Salesforce
Hightouch ID ColumnThe name of the column of the Hightouch query that contains a Salesforce object ID.
Hightouch to Salesforce Field MappingsA list of columns that will be updated for objects in Salesforce. Each time a sync occurs in Hightouch these columns will be updated.


In this mode, records that are present in the model with Salesforce's archive operation.

This mode is good for the following scenario:

  • You have objects in Salesforce you would like to archive and your model contains those records and only those records.

Object ID lookup

If you are attempting to associate two objects with a foreign key (for example, associate a contact with an account via the AccountId field in the contact), Hightouch can lookup the ID of an object based on another unique column and use the object ID as the value of the column.

In this example, the object has a reference field founder_lead__c which should contain the Salesforce ID of the Lead object of the founder. However, you may only have the external ID of the founder in your source in column founder.

With object ID lookup, you can look up the Lead object where the value in column founder equals the unique external ID field db_user_id__c and return the ID of the lead object as the value, syncing it to founder_lead__c.

Salesforce Person Account setup

If you need to send data to a Salesforce Person Account, here are the following steps:

  1. Contact Salesforce to enable Person Accounts

  2. Select Account in the Hightouch Sync configuration as your object (Person Account is not an API object, it's a copy of Account).

  3. You must sync LastName at a minimum instead of FullName to push to the object correctly (Otherwise, it will fail.)

Trouble merging data into Salesforce fields?

We only allow you to merge data from your source columns into Salesforce fields that are:

  • Set as External ID
  • Set as Unique
  • Not native Salesforce fields. Fields such as Salesforce's default 'email' field are native and can't be set as external identifiers. Thus you won't be able to merge on them. You'll need to create a new custom field with the same name.

Before trying to find fields in the Hightouch dropdown menu, you need to ensure the above is true for the fields you wish to merge on. Here's how:

  1. In Salesforce, find the "Sales" module and go to it:

  2. Go to Setup in the upper right:

  3. From within setup, find the Object Manager:

    Search for object manager

  4. Select the object you want to merge data into, for example, the contact object:

  5. At this point, you may either create a new custom field and set it to Unique and an External ID, or check an existing field to ensure it's unique and set to an external ID. Lets create a new one:

    Click on the "New" button in your chosen object

    Choose the field type you want to use

  6. Create a new custom field (we chose an e-mail field type in this example):

    Select the 2 required options as shown

    These 2 options must be selected in order for Hightouch to detect the fields in our configuration form dropdown. After ensuring these are checked, proceed by clicking the "Next" buttons in Salesforce to finish updating your object with the new custom field.

    Then come back to Hightouch. From the Salesforce destination configuration form, click the 'refresh' icon if needed to see the field available for selection. You should now be able to merge on it.

    You should now be able to find your field in the destination 'Field' dropdown menu

Multi object syncs

Hightouch supports syncing to multiple target objects, such as Contact or Lead and Account or Lead. When syncing to multiple objects, Hightouch checks to see if your external ID mapping maps to either object -- if so, it updates the appropriate object.

To use multi object syncs, make sure that your Lead's external ID field is mapped to the matching field on your Contact or Account:

  1. Find Lead in the Salesforce Object Manager.

  2. Go to Fields & Relationships.

  3. Go to Map Lead Field.

  4. Map your Lead's external ID to the matching field on the Contact or Account.

You may also map other fields that you want to carry over from Leads when they're converted.

Syncing custom picklist values

Sync modes

This integration only supports the All sync mode. In this mode, all active picklist values are replaced with each sync.

Sync configuration

Picklists are first filtered by the object they're associated with. Hightouch then allows you to specify the picklist whose values you wish to update:

Record matching

Custom picklist values contain two main fields "label" and "API Name" (also referred to as valueName). Both values must be unique amongst active values, though API Names must be unique across both inactive and active values within a picklist.

Records can be matched from your source to your Salesforce workspace by the API Name mapping of your choice:

Field mappings

You may also sync custom labels from your source to your custom picklist values in Salesforce:


Custom picklists may only contain a total of 1000 values (active and inactive) per picklist.

Syncing Platform Events

Sync modes

This integration uses the Insert sync mode, which means that a new Platform Event will be published when a new row appears in your model results. Row changes and row removals will be ignored by Hightouch. Salesforce Platform Events are immutable, so you can't update or delete events after they've been published.

Sync configuration

Platform Events first need to be created in your Salesforce instance. All created events will then be surfaced within the sync configuration in a dropdown for you to select.

Field mappings

Any column available from your model's results can be mapped to a platform event. It's important to note that Hightouch doesn't support creating Platform Event fields, so when creating your event in Salesforce, ensure you're including all the relevant fields.


Common errors

Error MessageExplanation
UNABLE_TO_LOCK_ROWThis error is caused by conflicting APEX or workflow processes. Salesforce can't work on a row while another process is touching it. Delete or pause the process or rerun sync when processes are finished.
CANNOT_UPDATE_CONVERTED_LEADWhen you convert a lead to a contact, account, or opportunity, it can't be updated as it doesn't exist anymore. The minute a lead is converted it's "soft" deleted from the leads object. You are no longer able to update this record.
INVALID_CROSS_REFERENCE_KEYThis error generally occurs when someone tries to sync ids from a different object or a different production or sandbox environment. It's a mismatch that Salesforce identifies for the user.
INVALID_FIELD_FOR_INSERT_UPDATEThis error often occurs when you try to update a read-only field. Visit your Salesforce object manager to confirm or change field types.
DUPLICATE_EXTERNAL_IDThis error occurs if you have records with the same IDs coming from an external system. Unique fields are unique to a record and can't be duplicated. This can happen when a lead or contact was imported with the wrong External CRM ID. This error can also appear when you have null values in your primary key.
INVALID_OR_NULL_FOR_RESTRICTED_PICKLISTThis error occurs when you attempt to sync invalid data into a picklist field, for example, the length is too long or the data type incorrect. Review the field's settings in Salesforce.

See Salesforce's comprehensive list of error messages and error codes for more.

High CPU limit

Customers may experience issues with pushing data into Salesforce because of the amount or complexity of their APEX triggers. The way to determine if your APEX is causing this High CPU Limit error message is to go into setup and search for "Bulk Data Load Jobs."

From here you will be able to see all of the bulk jobs that are hitting the API for your instance of Salesforce. To see the impact of this job run, select one of the most recent jobs, by clicking on the job ID.

Here we can see that there is no APEX impact on the far right side of the page with 0 time processing APEX. If your job has a high processing time, this will impact performance or cause High CPU limit errors.

The best course of action to solve the High CPU limit error is to drop your batch size in half. By default, Hightouch does batch sizes of 1,000. You can have a maximum of 10,000 records per batch. If you have dropped your batch size in half and are no longer encountering the error, you can continue to tune this by raising the batch size limit slowly. The other option is to simplify any APEX triggers or Process Flows that you have by consolidating superfluous code or limiting your SOQL queries to a more manageable size.

Missing fields in sync configuration

If you are missing an expected field when configuring syncs, try these tips:

  • Ensure fields you want to match against are set as external identifiers.
  • If you authenticated with your personal user ID, make sure you have permission to view and update the fields you want.
  • If you're missing the Salesforce ID field for matching on, make sure you're in the correct sync mode. Matching on Salesforce ID isn't supported for upserting.

When syncing to multi-objects, for example, Contact or Lead or Account or Lead, ensure both object types include a shared unique field marked as a Unique ID or a unique external ID. Without meeting this requirement, you won't see any fields populating for record matching.

Record matching on multi-objects in the Hightouch UI

Limitations on sandboxes

If you are building Hightouch syncs to Salesforce sandbox environments and encounter processing delays or errors, check the version of your Salesforce sandbox and upgrade to a higher version if necessary. You can find more information here: Salesforce Sandbox Licenses and Storage Limits by Type

Ready to get started?

Jump right in or a book a demo. Your first destination is always free.

Book a demoSign upBook a demo

Need help?

Our team is relentlessly focused on your success. Don't hesitate to reach out!

Feature requests?

We'd love to hear your suggestions for integrations and other features.

On this page

OverviewSupported syncingConnect to SalesforceAccess level recommendationsSyncing dataObject ID lookupSalesforce Person Account setupTrouble merging data into Salesforce fields?Multi object syncsSyncing custom picklist valuesSync modesSync configurationRecord matchingField mappingsLimitationsSyncing Platform EventsSync modesSync configurationField mappingsTroubleshootingCommon errorsHigh CPU limitMissing fields in sync configurationLimitations on sandboxes

Was this page helpful?