10

Map Salesforce data to Customer.io

When you set up a Salesforce integration with Customer.io, you’ll need to map your Salesforce data to people, custom objects, or events.

You’ll set up a sync for each kind of data you want to send through your pipeline. In most cases, you’ll want to follow our typical mappings. But the way you map your data to Customer.io depends on what you want to do with it—send messages, use it to trigger messages, or manage relationships!

Typical mappings

Remember, you’ll convert your Salesforce data to people, events, custom objectsAn object is a non-person entity that you can associate with one or more people—like a company, account, or online course., or relationships. You’ll see our typical mapping suggestions below.

Notice the * next to Leads! Leads fill multiple roles in Salesforce, so you might map them to people, objects, or both. We’ve provided more information about leads below to help you figure out how you want to map them to Customer.io.

The image below doesn’t show relationships. That’s because relationships aren’t a type of data themselves; rather, they’re a relationship between two data types. You won’t set the Data Pipelines format to relationships unless you have two other data types you need to relate to each other. For example, if you only sync contacts, you won’t need to sync relationships. But if you sync contacts and accounts, you’ll need to sync relationships to relate contacts to accounts! See Relationships: matching people to objects below for more information.

Note that the Data Pipelines format for objects and relationships affects which fields are available to sync. Different formats expose different sets of fields from your Salesforce objects and associated data (typically Contacts).

In general, you should use the Relationships format for if the Sync includes Relationships in the name. If you want to sync both object fields and relationship fields for the same Salesforce data type, you should create two separate syncs—one for the object itself (like “Accounts”) and another for the relationships to that object (like “Account Contact Relationships”).

What custom object name do I set for a custom object or relationship?

In most cases, we set this automatically for you. The Custom Object Name is simply an attribute we set in Customer.io that tells us what kind of Salesforce data your object (or relationship) originates from. If you create a new sync and the custom objectAn object is a non-person entity that you can associate with one or more people—like a company, account, or online course. doesn’t exist yet, don’t worry: you’ll create it in the Destination step when you set up your sync.

Relationship sync identifiers: matching people to objects

Salesforce treats people, custom objects, and the relationships between the two as discrete pieces of information. So, whenever you sync people and a kind of object, you’ll probably want to setup a separate Relationship sync between people and that object.

For example, when you sync accounts and contacts to Customer.io, you’ll also want to sync Account Contact Relationship information to capture relationships between your contacts and accounts. When you do this, you need to associate the ID of a person with the ID of an object. For accounts and contacts:

• The Field Containing Person ID is either the Contact ID or Contact.email
• The Field Containing Object ID is the Account ID

Relationship attributes

Like people and custom objects, relationships also contain attributesA key-value pair that you associate with a person or an object—like a person’s name, the date they were created in your workspace, or a company’s billing date etc. Use attributes to target people and personalize messages. describing the relationship—like whether someone is directly related to an account, a primary contact, and so on. These attributes help you find the right person by association with an object, like when you need to find an account’s primary contact, or all active participants in an opportunity.

These are the things you can bring in on the Fields tab. You’ll see them when you look at a person’s relationships!

Field mappings	Turn into relationship attributes!

How do I know if data is a person, event, or an object?

We’ve created a little decision tree to help you map data accordingly, but in short:

Leads are people in Customer.io

In Salesforce, a Lead represents multiple things: it’s an unqualified contact, an unqualified account, and a potential opportunity. But in Customer.io, the most common use case is to map leads to people so that you can foster your relationship with a person as they move through your sales process and become a qualified contact.

• (Recommended) map leads to people: If you want to send messages to your lead, attempting to qualify and nurture them, then they must be people. This is the most common use case when sending leads to Customer.io Journeys.
• Map leads to objects: If you just want to track the opportunity or company represented by a lead until you have a qualified contact, you can map them to objects. But remember: if you do this, you must have a person that you want to relate the object to!
• Map leads to relationships: If you want to capture a lead as both a person and an object related to that person, you can set up two separate syncs that map leads to both people and objects!

Identify people by email address

A common use case for syncing leads to Customer.io is to send messages to leads to nurture, qualify, and convert them to contacts. But where Salesforce gives a person a lead ID and then a different contact ID when they graduate to a contact, Customer.io expects a single ID for a person throughout their lifecycle. So how do we make sure that a lead and contact in Salesforce resolve to the same person in Customer.io? We identify leads and contacts by email address.

Beyond identifying people by email address, you should make sure that you store the lead_id and contact_id attributes in Customer.io. This gives you:

1. A way to determine when a lead graduates to a contact. (If the contact_id attribute exists, the person is a contact!)
2. A way to send data back into Salesforce, which expects you to identify leads and contacts by their Salesforce IDs. See Sending data back to Salesforce below for more information.

What happens if emails aren’t unique in Salesforce?

By default, emails aren’t required to be unique in Salesforce, but they are required to be unique by default in Customer.io. This means that you can have multiple contacts (or leads) with the same email address—though this is rare and generally not something you want to happen.

If two leads or contacts have the same email address in Salesforce, and you sync them to Customer.io, they’ll end up representing the same person in Customer.io—which could result in a muddled identity for your users.

If you’re worried about this happening, you can:

• Make email a unique field in Salesforce by creating a custom field in Salesforce to represent email addresses.
• Deduplicate your contacts and leads by using a Salesforce app. Search the Salesforce AppExchange for “dedupe” or “deduplicate” to find an app that will help you deduplicate your contacts and leads.

Leads become contacts associated with accounts and opportunities

When you qualify a lead in Salesforce, the record splits into those three things: a Contact related to an Account and an Opportunity. If you sync all three data types to Customer.io, then you’ll create or update records when you qualify the lead in Salesforce. So, whether you bring in a lead as a person or an object, it can eventually become a person and two related objects when you process or qualify it.

Sending data back to Salesforce

If you want to send contact and lead data from Customer.io back into Salesforce, you’ll need to store Contact IDs or Lead IDs in Customer.io.

In most cases, you’ll want to identify people by email address and store the Salesforce Contact ID or Lead ID in Customer.io as a contact_id or lead_id attribute. You’ll use these attributes to send data back to Salesforce, which expects you to identify people by their Salesforce IDs.

When you set up your Salesforce Destination, you’ll set the Who ID—the value Salesforce uses to identify a person; and this could be a lead_id or a contact_id. To make sure that you use the correct ID, you’ll use the coalesce function to use the contact ID if it exists, and fall back to the lead ID if it doesn’t in the format coalesce($.customer.contact_id, $.customer.lead_id).

Tasks are often events

In general, we suggest that you map tasks to events because:

• Tasks, like events, are assigned to a single person
• They represent things that people do
• You can use events to trigger campaigns, automating your task Salesforce list

Tasks in Salesforce are basically a single person’s to-do list for leads, accounts, opportunities and so on. While Salesforce doesn’t have a concept of “events,” tasks fit this bill, more or less, by changing states when you mark something off the to-do list.

Think of it this way: You aren’t likely to manage your task list in Customer.io. Instead, you probably want to automate your tasks or respond to changes in your to-do list. You may want to send a message to a contact when their bill is due, or send a message that invites a lead to schedule a meeting with you.

Convert your timestamps

Customer.io and Salesforce use different formats for dates and times. Salesforce uses ISO-8601 timestamps (like 2021-09-01T09:00:00Z) and Customer.io uses Unix timestamps (like 1630512000). This difference can prevent you from using Salesforce date and time values with some Customer.io features.

Luckily, you can automatically convert Salesforce’s timestamps to the format Customer.io expects. Go to Data & Integrations > Integrations and select the Connections tab. Then select your workspace and click Actions. Edit each actionThe source event and data that triggers an API call to your destination. For example, an incoming identify event from your sources adds or updates a person in our Customer.io Journeys destination. and set Convert dates to Unix timestamps setting to true, and we’ll automatically convert incoming timestamps to support Customer.io.

Converting Salesforce timestamps to Customer.io’s Unix format lets you use Salesforce dates and times for things like for date-based conditions in segmentsA group of people who match a series of conditions. People enter and exit the segment automatically when they match or stop matching conditions. or date-triggered campaigns.