Add people and events

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

 We call this identifying people

When you add a person, you “identify” them for Customer.io, so we sometimes use “adding people” and “identifying people” interchangeably.

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.

MethodUse Case
UIQuick, simple way to add individuals that slip through other identification methods.
CSVQuickly import a list of people from another system or to create a manual segment—a static group of people.
JavaScript snippetSimple path to integrating with Customer.io, makes it easy to identify new people without writing your own code.
Custom form submissionsAdd people to your workspace when they fill out a form on your website.
Facebook Lead Ad formsAdd people to your workspace when they fill out a Facebook Lead Ad form.
Database Sync integrationSync people from your MySQL or Postgres database on a regular interval, keeping your workspace up to date with data from other backend systems
API/LibrariesThe most flexible way to add people to, and update people in, Customer.io. While this path requires development resources, fully integrating with Customer.io provides the most flexibility when adding and updating people.
Create or update people actionProvides a way to create a person from the data available within the current campaign.

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.

 You can store email addresses in other attributes

If you set email as a unique identifier, the email attribute itself, which you’ll use to identify people, must be unique. But, you can store email addresses in other attributes that are not unique—like a person’s support representatives or a friends list!

 When using email as an identifier, email addresses are case insensitive

To enforce uniqueness among emails when using email as an identifier, we treat person@example.com and PERSON@example.com as duplicates; these addresses represent the same person.

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.

The cio_id appears in a person's attributes
The cio_id appears in a person's attributes

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.
flowchart LR a[identify person
by cio_id]-->b{does cio_id exist} b-->|no|d[ignore request] b-->|yes|c{are this person's
identifiers suppressed?} c-->|no|h{Does the request
include identifiers?} c-->|yes|f[ignore request and suppress
identifiers that aren't already suppressed] h-->|no|g[update person's
attributes] h-->|yes|i[update person's
identifiers and attributes]

 cio_id is known as internal_customer_id in our data warehouse integrations

If you use our data warehouse sync integration, many of the tables include internal_customer_id and external_customer_id. These map to cio_id and id respectively.

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.

flowchart TD e["update email
#40;where id and email are identifiers#41;"] --> f{is it set?} f -->|yes|h{"is #quot;cio_id
or id#quot; enabled?"} h -->|yes|j[you can set
email with id] h -->|no|i[you must update
email with cio_id] f -->|no|g[you can update
email with id] a["update id
#40;where email and id are identifiers#41;"] --> b{is it set?} b ---> |yes|k[you can update
id with cio_id] b ---> |no|c[you can set
id with email] n["update id
#40;where id is the only identifier#41;"] --> o{is it set?} o --> |yes|p{"is #quot;cio_id
or id#quot; enabled?"} o --> |no|q[person does
not exist] p --> |yes|r[you can update
id with cio_id] p --> |no|s[you cannot update id]

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.

 If you see Failed Attribute Changes, try changing your workspace settings

Integrations and API requests that change a person’s email address can be a frequent source of Failed Attribute Change errors. You can enable the Allow updates to email using ID setting under Settings > Workspace Settings > General Workspace Settings to make it easier to change people’s email values after they are set and avoid Failed Attribute Change errors.

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, then you cannot change a person’s id after you set by default. If you want to be able to change id after you set it (using cio_id) you must change your workspace settings.

  1. Go to Workspace > Workspace Settings and click General Workspace Settings.
  2. Next to id, select Reference people by cio_id.
enable reference people by cio_id to allow updates to IDs
enable reference people by cio_id to allow updates to IDs

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.

ID in payloadID in path
  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.

 If you have duplicate profiles, try the auto-merge feature

If you perform multiple requests in rapid succession when you create a person, there’s a danger that you could create multiple versions of the same person—one with an id and one with an email. You can turn on the Multi-identifier profile merge feature to automatically combine these profiles.

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.

attribute change failure
attribute change failure

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.

flowchart LR subgraph Account direction LR b[Angela] c[Oscar] d[Kevin] end Account-->|bill_date is < 30 days from now|e[Send a broadcast
to the account] e-->f[Angela gets
bill due message] e-->g[Oscar gets
bill due message] e-->h[Kevin gets
bill due message]
Copied to clipboard!
  Contents
Is this page helpful?