Salesforce (Actions) Destination

Destination Info

Additional versions of this destination are available

This page is about the Salesforce (Actions) Destination. See below for information about other versions of the Salesforce destination:

Segment’s Salesforce (Actions) destination allows you to create, update or upsert records for any object type. Segment sends data to the Salesforce REST API.

Benefits of Salesforce (Actions) Destination vs Salesforce Destination Classic

The Salesforce (Actions) destination provides the following benefits over the classic Salesforce destination:

  • Fewer settings. Data mapping for actions-based destinations happens during configuration, which eliminates the need for most settings.
  • Clearer mapping of data. Actions-based destinations enable you to define the mapping between the data Segment receives from your source, and the data Segment sends to Salesforce.
  • OAuth 2.0 support. Authentication with Salesforce leverages OAuth 2.0 instead of a username/password.
  • Flexible match keys. Upsert and update records based on any match key, including external IDs, record IDs, email and other object fields.

Getting started

Before you connect Segment to Salesforce, please ensure you have a Salesforce account with REST API access.

  1. From the Segment web app, click Catalog, then click Destinations.
  2. Search for Salesforce in the Destinations Catalog, and select the destination.
  3. Click Configure Salesforce in the top-right corner of the screen.
  4. Select the source that will send data to Salesforce, follow the steps to name your destination, and select Actions as the destination framework.
  5. On the Settings tab, authenticate with Salesforce using OAuth.
  6. Follow the steps in the Destinations Actions documentation on Customizing mappings. You must select which Event Types and/or Event Names will trigger each mapping.
  7. Enable the destination and configured mappings.

Destination Settings

Setting Description
Sandbox Instance Required.

Enable to authenticate into a sandbox instance. You can log in to a sandbox by appending the sandbox name to your Salesforce username. For example, if a username for a production org is user@acme.com and the sandbox is named test, the username to log in to the sandbox is user@acme.com.test. If you are already authenticated, please disconnect and reconnect with your sandbox username.

Available Actions

Build your own Mappings! Combine supported triggers with the following Salesforce-supported actions:

Mapping limits per destination

Individual destination instances have support a maximum of 50 mappings.

Custom Object

Create, update, or upsert records in any custom or standard object in Salesforce.

Custom Object is a Cloud action.

Click to show / hide fields

Field Description
Operation* Type: STRING

The Salesforce operation performed. The available operations are Create, Update or Upsert records in Salesforce.

Use Salesforce Bulk API Type: BOOLEAN

If true, events are sent to Salesforce’s Bulk API 2.0 rather than their streaming REST API. Once enabled, Segment will collect events into batches of 1000 before sending to Salesforce. Enabling Bulk API is not compatible with the create operation.

Record Matchers Type: OBJECT

The fields used to find Salesforce records for updates. This is required if the operation is Update or Upsert.

Any field can function as a matcher, including Record ID, External IDs, standard fields and custom fields. On the left-hand side, input the Salesforce field API name. On the right-hand side, map the Segment field that contains the value.

If multiple records are found, no updates will be made. Please use fields that result in unique records.


Bulk Upsert External Id Type: OBJECT

The external id field name and mapping to use for bulk upsert.

Bulk Update Record Id Type: STRING

The record id value to use for bulk update.

Salesforce Object* Type: STRING

The API name of the Salesforce object that records will be added or updated within. This can be a standard or custom object. Custom objects must be predefined in your Salesforce account and should end with “__c”.

Other Fields* Type: OBJECT

Additional fields to send to Salesforce. On the left-hand side, input the Salesforce field API name. On the right-hand side, map the Segment field that contains the value.

This can include standard or custom fields. Custom fields must be predefined in your Salesforce account and the API field name should have __c appended.


Contact

Create, update, or upsert contacts in Salesforce.

Contact is a Cloud action.

Click to show / hide fields

Field Description
Operation* Type: STRING

The Salesforce operation performed. The available operations are Create, Update or Upsert records in Salesforce.

Use Salesforce Bulk API Type: BOOLEAN

If true, events are sent to Salesforce’s Bulk API 2.0 rather than their streaming REST API. Once enabled, Segment will collect events into batches of 1000 before sending to Salesforce. Enabling Bulk API is not compatible with the create operation.

Record Matchers Type: OBJECT

The fields used to find Salesforce records for updates. This is required if the operation is Update or Upsert.

Any field can function as a matcher, including Record ID, External IDs, standard fields and custom fields. On the left-hand side, input the Salesforce field API name. On the right-hand side, map the Segment field that contains the value.

If multiple records are found, no updates will be made. Please use fields that result in unique records.


Bulk Upsert External Id Type: OBJECT

The external id field name and mapping to use for bulk upsert.

Bulk Update Record Id Type: STRING

The record id value to use for bulk update.

Last Name Type: STRING

The contact’s last name up to 80 characters. This is required to create a contact.

First Name Type: STRING

The contact’s first name up to 40 characters.

Account ID Type: STRING

The ID of the account that this contact is associated with. This is the Salesforce-generated ID assigned to the account during creation (i.e. 0018c00002CDThnAAH).

Email Type: STRING

The contact’s email address.

Mailing City Type: STRING

City for the contact’s mailing address.

Mailing Postal Code Type: STRING

Postal Code for the contact’s mailing address.

Mailing Country Type: STRING

Country for the contact’s mailing address.

Mailing Street Type: STRING

Street number and name for the contact’s mailing address.

Mailing State Type: STRING

State for the contact’s mailing address.

Other Fields Type: OBJECT

Additional fields to send to Salesforce. On the left-hand side, input the Salesforce field API name. On the right-hand side, map the Segment field that contains the value.

This can include standard or custom fields. Custom fields must be predefined in your Salesforce account and the API field name should have __c appended.


Opportunity

Create, update, or upsert opportunities in Salesforce.

Opportunity is a Cloud action.

Click to show / hide fields

Field Description
Operation* Type: STRING

The Salesforce operation performed. The available operations are Create, Update or Upsert records in Salesforce.

Use Salesforce Bulk API Type: BOOLEAN

If true, events are sent to Salesforce’s Bulk API 2.0 rather than their streaming REST API. Once enabled, Segment will collect events into batches of 1000 before sending to Salesforce. Enabling Bulk API is not compatible with the create operation.

Record Matchers Type: OBJECT

The fields used to find Salesforce records for updates. This is required if the operation is Update or Upsert.

Any field can function as a matcher, including Record ID, External IDs, standard fields and custom fields. On the left-hand side, input the Salesforce field API name. On the right-hand side, map the Segment field that contains the value.

If multiple records are found, no updates will be made. Please use fields that result in unique records.


Bulk Upsert External Id Type: OBJECT

The external id field name and mapping to use for bulk upsert.

Bulk Update Record Id Type: STRING

The record id value to use for bulk update.

Close Date Type: STRING

Date when the opportunity is expected to close. Use yyyy-MM-dd format. This is required to create an opportunity.

Name Type: STRING

A name for the opportunity. This is required to create an opportunity.

Stage Name Type: STRING

Current stage of the opportunity. This is required to create an opportunity.

Amount Type: STRING

Estimated total sale amount.

Description Type: STRING

A text description of the opportunity.

Other Fields Type: OBJECT

Additional fields to send to Salesforce. On the left-hand side, input the Salesforce field API name. On the right-hand side, map the Segment field that contains the value.

This can include standard or custom fields. Custom fields must be predefined in your Salesforce account and the API field name should have __c appended.


Account

Create, update, or upsert accounts in Salesforce.

Account is a Cloud action. The default Trigger is: type = "group"

Click to show / hide fields

Lead

Create, update, or upsert leads in Salesforce.

Lead is a Cloud action. The default Trigger is: type = "identify"

Click to show / hide fields

Field Description
Operation* Type: STRING

The Salesforce operation performed. The available operations are Create, Update or Upsert records in Salesforce.

Use Salesforce Bulk API Type: BOOLEAN

If true, events are sent to Salesforce’s Bulk API 2.0 rather than their streaming REST API. Once enabled, Segment will collect events into batches of 1000 before sending to Salesforce. Enabling Bulk API is not compatible with the create operation.

Record Matchers Type: OBJECT

The fields used to find Salesforce records for updates. This is required if the operation is Update or Upsert.

Any field can function as a matcher, including Record ID, External IDs, standard fields and custom fields. On the left-hand side, input the Salesforce field API name. On the right-hand side, map the Segment field that contains the value.

If multiple records are found, no updates will be made. Please use fields that result in unique records.


Bulk Upsert External Id Type: OBJECT

The external id field name and mapping to use for bulk upsert.

Bulk Update Record Id Type: STRING

The record id value to use for bulk update.

Company Type: STRING

The lead’s company. This is required to create a lead.

Last Name Type: STRING

The lead’s last name. This is required to create a lead.

First Name Type: STRING

The lead’s first name.

Email Type: STRING

The lead’s email address.

City Type: STRING

City for the lead’s address.

Postal Code Type: STRING

Postal code for the lead’s address.

Country Type: STRING

Country for the lead’s address.

Street Type: STRING

Street number and name for the lead’s address.

State Type: STRING

State for the lead’s address.

Other Fields Type: OBJECT

Additional fields to send to Salesforce. On the left-hand side, input the Salesforce field API name. On the right-hand side, map the Segment field that contains the value.

This can include standard or custom fields. Custom fields must be predefined in your Salesforce account and the API field name should have __c appended.


Case

Create, update, or upsert cases in Salesforce.

Case is a Cloud action.

Click to show / hide fields

Field Description
Operation* Type: STRING

The Salesforce operation performed. The available operations are Create, Update or Upsert records in Salesforce.

Use Salesforce Bulk API Type: BOOLEAN

If true, events are sent to Salesforce’s Bulk API 2.0 rather than their streaming REST API. Once enabled, Segment will collect events into batches of 1000 before sending to Salesforce. Enabling Bulk API is not compatible with the create operation.

Record Matchers Type: OBJECT

The fields used to find Salesforce records for updates. This is required if the operation is Update or Upsert.

Any field can function as a matcher, including Record ID, External IDs, standard fields and custom fields. On the left-hand side, input the Salesforce field API name. On the right-hand side, map the Segment field that contains the value.

If multiple records are found, no updates will be made. Please use fields that result in unique records.


Bulk Upsert External Id Type: OBJECT

The external id field name and mapping to use for bulk upsert.

Bulk Update Record Id Type: STRING

The record id value to use for bulk update.

Description Type: STRING

A text description of the case.

Other Fields Type: OBJECT

Additional fields to send to Salesforce. On the left-hand side, input the Salesforce field API name. On the right-hand side, map the Segment field that contains the value.

This can include standard or custom fields. Custom fields must be predefined in your Salesforce account and the API field name should have __c appended.


Configuration options

Operations

When configuring a mapping, you must select the Operation that will be performed on the record. The Salesforce (Actions) destination supports the following operations:

  • Create. Pushes new records to Salesforce. This operation is good for the following scenarios:
    • Push records into Salesforce, but don’t need data within each row to remain up to date.
    • Static data where each row is never updated, such as events.
  • Upsert. Pushes new records to Salesforce and updates fields on existing records in Salesforce. This operation is good for the following scenarios:
    • Push records into Salesforce and keep the data up to date.
  • Update. Updates fields on existing records in Salesforce. This operation is good for the following scenarios:
    • You have records in Salesforce that you want to add new information/fields to.
    • You want to update fields on existing records in Salesforce.

Record Matchers

When using the update and upsert operations, you must specify the match key(s) that will be used to query Salesforce for the record. You can do this within the Record Matchers object. Any field can be used as a record matcher, including:

  • External IDs. To map an External ID, the Salesforce API name should have __c appended to it.
  • Record IDs. To map a Record ID, the Salesforce API name is Id.
  • Standard fields. To map a standard field, the Salesforce API name should match what is in Salesforce for the given field, for example Email.
  • Custom fields. To map a custom field, the field needs to be predefined in Salesforce and the Salesforce API name should have __c appended to it.

If multiple fields are provided in the Record Matchers object, Segment uses an “OR” operator to query Salesforce for a record. If multiple records are returned upon query, no updates will be made. Segment will instead record a 300 error status for the request, and the request will not be retried. Please use fields that result in unique records.

Please note Salesforce only allows querying on fields that have the “Filter” property. For example, we cannot query on the Case Description because it is not a filterable property. You can lookup the standard field properties in Salesforce’s API documentation to determine if a field is available for querying.

the filter property

FAQ

How do I enable a sandbox instance?

To send data to a Salesforce sandbox instance, navigate to Settings > Advanced Settings, toggle on the “Sandbox Instance” setting, and authenticate. If you are already authenticated, please disconnect and reconnect with your sandbox username.

Your Salesforce sandbox username appends the sandbox name to your Salesforce production username. For example, if a username for a production org is user@acme.com and the sandbox is named test, the username to log in to the sandbox is user@acme.com.test.

How do I add custom fields?

Custom fields can be included in the Other Fields mapping. Custom fields must be predefined in your Salesforce account and should end with __c (i.e. My_Custom_Field__c). Please include the __c in your mapping.

You can see Salesforce API names in Salesforce under Setup > Objects and Fields > Object Manager > Select your object > Fields & Relationships > FIELD NAME.

the custom fields

See Salesforce’s Create Custom Fields for more information on custom fields.

How do I associate a Contact with an Account?

The only way to associate a Contact with an Account is to include the AccountId on the Contact record. The AccountId is a Salesforce-generated ID assigned to the account during creation (i.e. 0018c00002CDThnAAH). Salesforce only accepts a single AccountId as the Contact’s primary account; you cannot pass an array of IDs.

The AccountId is different than the AccountNumber and AccountName. The AccountId is auto-generated, whereas the AccountNumber and AccountName are chosen by you.

How do I send data for Person Accounts?

A Person Account is a special type of account that represents an individual rather than a business. The requirements for Person Account records differ from what Segment’s standard Account action supports. For example, Name is required for Accounts, whereas LastName is required for Person Accounts. To send data for Person Accounts, you must use the Custom Object action. Hard code the Salesforce Object to Account and define other standard and custom fields, such as LastName and FirstName, in the Other Fields mapping.

Mapping configuration for a Person account

Person Accounts are not enabled by default, and the solution above will only work if you have Person Accounts enabled. If you do not have Person Accounts enabled, please use the standard Account action.

How many API calls does Segment make to Salesforce?

  • For update and upsert, the query request used to determine whether the record already exists in Salesforce counts as one API call. A second API call is used to update or create that record.
  • For create, no query is executed so one API call is used to create the record.

To check how many API calls you have left in Salesforce, go to Setup > Company Settings > Company Information, and you’ll find a field labeled: API Requests, Last 24 Hours.

Why do I see duplicate records in Salesforce?

When using the create operation, it’s possible for duplicate records to be created in Salesforce. This is because Segment retries records once they hit the internal timeout. It’s possible Salesforce’s REST API eventually processes the original record in addition to the retried record, resulting in duplicates. You may encounter this behavior if Salesforce’s REST API throttles your records (for example, due to hitting API limits or complex workflow automation). To prevent duplicates, you can use Duplicate Rules in Salesforce. See set up information in Resolve and Prevent Duplicate Data in Salesforce.

Please note this is only a concern when using the create operation. You can use the upsert operation instead to avoid duplicates if upsert meets your needs.

Can I send data to the Salesforce Bulk API 2.0?

Segment is in the process of adding support for the Bulk API to help reduce API calls made to Salesforce. This is not yet available.

This page was last modified: 01 Dec 2022



Get started with Segment

Segment is the easiest way to integrate your websites & mobile apps data to over 300 analytics and growth tools.
or
Create free account