Salesforce Destination
About this integration
Our Salesforce destination helps you create, update, or upsert records for any object type. Customer.io sends data to the Salesforce REST API.
Getting started
Go to the Data Pipelines tab and click Connections.
Click Add New under Destinations.
Select the Salesforce destination.
(Optional) Select the sources that you want to connect to this destination. You can always connect sources to your destination later. We’ll only show you eligible sources.
Configure your destination.
Instance Url: The user specific instance URL returned by Salesforce Oauth. This setting is hidden to the user and set by Oauth Service.
Is Sandbox: 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.
Click Enable Destination.
Actions
When you’re done setting up your destination, you can go to the Actions tab to see how we map source events to your destination.
You may need to add actions for this destination
While we often have default triggers for actions, we don't always add those actions as defaults. You may need to add actions to make sure that you're sending all the data that you want to send to your destination. See our actions page for help setting up actions.
| Action | Default Trigger | Description |
|---|---|---|
| Lead |
| Create, update, or upsert leads in Salesforce. |
| Custom Object | Create, update, or upsert records in any custom or standard object in Salesforce. | |
| Case | Create, update, or upsert cases in Salesforce. | |
| Contact | Create, update, or upsert contacts in Salesforce. | |
| Opportunity | Create, update, or upsert opportunities in Salesforce. | |
| Account |
| Create, update, or upsert accounts in Salesforce. |
Mapping actions to Salesforce Operations
When you set up an action, you’ll select the Operation that you want to perform on a record. Salesforce destination supports the following operations:
- Create: Pushes new records to Salesforce. This operation works when you want to push new records but don’t need data within each row to remain up to date or when you’re working with static data that you won’t update later, like events.
- Upsert: Pushes new records to Salesforce and updates fields on existing records in Salesforce. This operation helps you push records into Salesforce and keep data up to date.
- Update: Updates fields on existing records in Salesforce. This operation works when you know that you already have records in Salesforce that you update or add new information to
- Delete: Deletes existing records in Salesforce.
Matching records with delete, update, and upsert
When you use the delete, update and upsert operations, you need to specify one or more Record Matchers. A record matcher is a value we’ll query Salesforce for to find and match the records you want to upsert, delete, or update. You can use any field in your source data as a record matcher, including:
- External IDs. To map an External ID, the Salesforce API name should have
__cappended 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
__cappended to it.
You can also set the Record Matchers Operator if you have multiple record matchers. This determines whether Salesforce matches on any record matcher (OR), or all record matchers (AND). If you have multiple Record Matchers, you should use fields that result in unique records. If the operator is set to Or and Salesforce finds multiple matching records, it won’t perform the operation. We’ll record a 300 status for the request, and will not retry it.
Note that you should only set Record Matchers that that have the “Filter” property in Salesforce; these are fields Salesforce can query. For example, we can’t perform a Salesforce query on the Description field 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 is a valid Record Matcher.
FAQ
How do I enable a sandbox instance?
To send data to a Salesforce sandbox instance, go to your destination’s Settings, enable the Sandbox Instance setting and click Connect. If you already connected to a different Salesforce instance, you’ll need to disconnect and reconnect with your sandbox username.
Your Salesforce sandbox username is your Salesforce production username with your sandbox name at the end. For example, if your username for a production instance is user@example.com and your sandbox is named test, your sandbox username is user@example.com.test.
How do I add custom fields?
You can add additional, custom fields to any action under Additional Fields. You must define fields in Salesforce before you send them from your source data. When you set up custom fields in Salesforce, the names of your custom fields should end with __c (for example, My_Custom_Field__c). You should 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.
See Salesforce’s Create Custom Fields documentation for more information.
How do I associate a Contact with an Account?
To associate a Contact with an Account, you must include the AccountId on the Contact record. The AccountId is a Salesforce-generated ID assigned to the account when you create it (i.e. 0018c00002CDThnAAH). Salesforce only accepts a single AccountId as the Contact’s primary account; you can’t pass an array of IDs.
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. Our standard Account action isn’t designed for Person Accounts, so you’ll need to use our Custom Object action if you want to map data to Person Accounts.
Person Accounts have specific field requirements. For example, Name is required for Accounts, but LastName is required for Person Accounts. Hard code the Salesforce Object to Account and define other standard and custom fields, such as LastName and FirstName, in the Other Fields mapping.
How many API calls do you make to Salesforce?
The update and upsert operations take two API calls per action—one as a query to determine whether a record already exists in Salesforce or not and a second API call to update or create that record.
All other operations are a single call. 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.
How does Salesforce Bulk API work?
When you enable Use Salesforce Bulk API is enabled for an action, we send data to Salesforce’s Bulk API 2.0 rather than their streaming REST API. We’ll collect source data in batches of 1000 calls before we perform actions in Salesforce. You can only use the bulk API for upsert or update operations.
For bulk update, if a record in a batch is missing a Bulk Update Record ID, we still send it to Salesforce. Salesforce will reject the individual record because it won’t find a record to update. But Salesforce will still process other records in the batch.
When records fail this way, the Data Out tab won’t report it. We’ll show the entire batch as successful because we only know if the bulk request is successful or not; we don’t know the status of individual records in the batch.
