11

Add people and events

You add people to your workspace using their unique, identifiers—normally their email address or ID.

You can add people using any of the unique identifiers that your workspace supports. Go to Settings > Workspace Settings > General Workspace Settings to see the identifiers supported by your workspace.

Ways to add people

You can add people to your workspace through the UI, by uploading CSVs, or programmatically using our JavaScript snippet, APIs, or libraries. Each method has its benefits and use cases. In general, you can import people in bulk using CSVs, and all other operations identify individuals.

While you can add and update people using all of the methods below, not all of these methods let you update people’s identifiers after they are set. For example, if you identify people by both user ID and email address, and a person wants to change the email address associated with their User ID, you cannot change that person’s email address by uploading a CSV.

To update identifiers (after they are initially set) using the API or our libraries, you must reference a person by their cio_id.

Identifiers for people

Identifiers are unique values that represent people, like an email address or a user id. You identifyThe Customer.io operation that adds or updates a person. When you identify a person, Customer.io either adds a person if they don’t exist in your workspace, or updates them if they do. Before you identify someone (by their email address or an ID), you can track them anonymously., add, and update people using their identifiers.

When you create your workspace, you determine the identifiers that you want to support. By default, workspaces identify people by email or id.

• email: A person’s email address. You may want to use this identifier to track leads before they become customers.
• id: A unique identifier that you assign a person. Generally, this value represents a person in your backend systems, like a unique user name or user ID of someone who has an account with you.

If your workspace supports multiple identifiers, you can create a person using a single identifier, and assign or update other identifiers later.

cio_id: The canonical identifier

When you identify a person, Customer.io generates a unique, immutable cio_idAn identifier for a person that is automatically generated by Customer.io and cannot be changed. This identifier provides a complete, unbroken record of a person across changes to their other identifiers (id, email, etc). for them. You’ll see this value in a person’s attributes when you select them from the People page, or when you look up a person using the App API.

In identifyThe Customer.io operation that adds or updates a person. When you identify a person, Customer.io either adds a person if they don’t exist in your workspace, or updates them if they do. Before you identify someone (by their email address or an ID), you can track them anonymously. calls to our API (and some integrations), this identifier acts as an override for other identifiers: if you use cio_id, we use that identifier, and only that identifier, to find and update a person. When you identify people by cio_id, you can update a person’s other identifiersThe attributes you use to add, modify, and target people. Each unique identifier value represents an individual person in your workspace..

When you send an identify a person by cio_id:

• You can update that person’s other identifiers.
• If the cio_id does not exist, or belongs to a person who was deleted, we’ll ignore the request. (You can’t update a person who does not exist.)
• If any identifier in the request belongs to a suppressed identifier, we’ll suppress other identifiers in the request.

Updating identifiers

Depending on your workspace configuration, you may create a person without setting all of their identifiersThe attributes you use to add, modify, and target people. Each unique identifier value represents an individual person in your workspace., or need to change an identifier value after you set it.

For example, a person might enter your workspace with an email address as a lead and generate an id when they become a customer later. Or a customer might want to change the email address associated with their account later.

The rules determining how you change identifiers depend on your workspace settings, the type of identifier you want to change, and whether those identifiers are already set (they aren’t null). In a workspace that only identifies people by ID, you cannot change an id after it is set by default, but you can change your workspace settings to make id mutable.

If an identifier is not set, you can set it at any time, using any method you would normally use to create or update a person.

If an identifier is set in an ID only workspace: If an ID is not yet set, you will create a person. After you set an ID, you cannot change it unless you change your workspace settings. You can set email at any time.

If an identifier is set in a workspace where both email and ID are identifiers

• You can change a person’s id with cio_id through the People page or the API. You cannot change id values when uploading a CSV or through a database integration (MySQL, Google BigQuery Data In, etc.)
• You can change a person’s email using their id if the Allow updates to email using ID workspace setting is enabled; otherwise, you must identify the person by cio_id to change their email address.

Updating a person’s ID

If your workspace uses email as an identifierThe attributes you use to add, modify, and target people. Each unique identifier value represents an individual person in your workspace., you can change a person’s id using cio_id.

But, if your workspace does not use email as an identifier, you have to change the default setting so ids are modifiable:

1. Go to Workspace Settings and click General Workspace Settings.
2. Next to id, select Reference people by cio_id.

Add and update people using the API

You add and update people using the same method for the track API. API requests to add or update people must include an identifier in the path; you can also include identifiers in the request payload itself. You add or update a person depending on whether or not the identifier value(s) in your request belong to an existing person.

Add a person: If none of the identifiers in your request belong to an existing person in your workspace, your request adds a new person.

Update a person: If any identifier in your request belongs to a person in your workspace, your request updates that person, including setting any identifier values that weren’t previously set. It doesn’t matter whether the new identifier is in the path or the request payload.

For example, if your workspace supports multiple identifiers—email, id, etc—you might not always set both identifiers when you add a person. Like when a person enters your workspace as a lead (by email) and graduates to a customer (they generate a user id). Because you can provide the ID value in the path or the payload, these requests are functionally the same; both set an ID on the person with the email address person@example.com.

  curl --request PUT \
  --url https://track.customer.io/api/v1/customers/person@example.com \
  --header "Authorization: Basic $(echo -n site_id:api_key | base64)" \
  --header 'content-type: application/json' \
  --data '{"id":"id1234"}'

  curl --request PUT \
  --url https://track.customer.io/api/v1/customers/id1234 \
  --header "Authorization: Basic $(echo -n site_id:api_key | base64)" \
  --header 'content-type: application/json' \
  --data '{"email":"person@example.com"}'

If your request includes identifiers belonging to different people, your request may result in an Attribute Update Failure.

Troubleshooting Failed Attribute Change errors

Failed Attribute Change errors typically occur due to mismatched identifiersThe attributes you use to add, modify, and target people. Each unique identifier value represents an individual person in your workspace. in the request: an ID or email that does not match the values on the identified profile. If you see a lot of these kinds of errors and you notice failed requests typically include email attributes, you can try enabling the Allow updates to email using ID and Multi-identifier profile merge settings to fix the issue.

API requests prioritize the identifier in the path of the request. If the identifier in the payload of your request doesn’t belong to the person in the path, the request may complete normally but result in a Failed Attribute Change for the identifier in the request body. The rest of the attributes in your request are applied to the person in the path of your request.

If you want to add a new person, your request cannot specify identifiers belonging to a person in your workspace. If you want to update a person’s identifiers after they are set, see the section below.

 API requests that return 200 OK can still result in Attribute Change failures

Properly formed requests to the Track API, which you use to add and update people, are generally accepted, but may result in Attribute Change failures if you include identifiers belonging to different people.

Updating identifiers using the API

If a person has an id, you want to set or change their email identifier, and you’ve enabled the Allow updates to email using ID workspace setting, you can simply send a normal request.

In all other cases, you need to identify a person by their cio_idAn identifier for a person that is automatically generated by Customer.io and cannot be changed. This identifier provides a complete, unbroken record of a person across changes to their other identifiers (id, email, etc).—in the format cio_<cio_id_value>—to change their identifiersThe attributes you use to add, modify, and target people. Each unique identifier value represents an individual person in your workspace.. You can look up a person to find their cio_id. Your request to update a person’s identifiers after they’re set should look something like:

curl --request PUT \
--url https://track.customer.io/api/v1/customers/cio_03000001 \
--header "Authorization: Basic $(echo -n site_id:api_key | base64)" \
--header 'content-type: application/json' \
--data '{"email":"new_person@example.com"}'

Leads and Customers

A common use case is to identify people first by their email addresses when they express interest in your products or services—when they are leads—and assign them IDs when you convert them to customers or users.

In general, the process of graduating leads to customers uses our default workspace settings—in which both email and id are unique identifiers, and works like this:

1. Identify a person by email.
2. Send person through one or more campaigns trying to convert them to a customer.
3. Customer achieves a conversion event, becoming a customer.
4. Update the person.
   • UI: Create an event-triggered campaign using the event containing people’s new ID value, and include an Create or update person action to your campaign that assigns a person’s ID from the event trigger.
   • API: Perform an identify request referencing the existing person’s email address and their new ID. It doesn’t matter whether the email of the existing person is in the request path or payload.

Relate people to objects

Objects are a new feature that let you group people in your workspace, like accounts that people belong to, flights they’ve booked, or online courses they’ve enrolled in.

Objects have their own attributes, providing a way to relate data to a group of people in your audience. For example, you might message everybody related to an account object to let them know that it’s time for their yearly renewal. Without objects, you’d need to set attributes or send an event for every individual member of the account! But with objects, you can handle this one-to-many relationship the easy way. Learn more about objects and relationships.