Objects
Not to be confused with JSON objects, an Object is a way to group people, like an account that people belong to, online courses that people enroll in, or recreational leagues that people can join.
This page covers object types and objects. Object types are the kinds of non-people things that you want to track in Customer.io—like companies, online classes, accounts, etc. An object is an individual thing—a single company, online class, or account—that you want to relate to one or more people.
As of July 1, 2023, objects will be a paid feature.
Check out our plans and how we bill to learn more.
How it works
Objects let you group and relate data to people in your workspace, like accounts that people belong to, flights they’ve booked, or online courses they’ve enrolled in. Objects show up in the menu under People.


Each object has its own 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. that you can use with liquidA syntax that supports variables, letting you personalize messages for your audience. For example, if you want to reference a person’s first name, you might use the variable {{customer.first_name}}
. to personalize messages.
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.
bill_date
is < 30 days from now|e[Send a broadcastto the account] e-->f[Send message
to Angela] e-->g[Send message
to Oscar] e-->h[Send message
to Kevin]
Quick Start
If you’re ready to try things out right away, here are the high points:
- Go to Companies in the side menu to get started.
- Create objects and relate them to people in the UI or programmatically.
- SegmentA group of people who match a series of conditions. People enter and exit the segment automatically when they match or stop matching conditions. people by relationships and use these segments in Newsletters and Campaigns.
Planned updates for this feature
Objects are a new feature, but it’s one you can be confident in. We’re committed to expanding their use across our entire platform, so here are some of our future plans. Is there something in particular you’d like to accomplish with objects or object-relationships? Let us know.
Within the next few months
Trigger campaigns based on people’s relationships to objects. Available as of February 14, 2023! You can relate a person to multiple objects matching a set of conditions, but, for now, they’ll only trigger a campaign journey for the first such relationship. See the section below for more information.
Support for multiple object types. Available as of May 11, 2023! You can support a variety of grouping mechanisms in your workspace—companies, accounts, online classes, and any other groups your audience might belong to.
Full control over object relationships and object types in the UI/API. Available as of May 25, 2023! You can now relate objects to people from the UI, which means you now have full control over creating objects and relating them to people via UI and APIs.
Trigger campaigns based on changes to objects
Right now, you can only trigger campaigns based on segments that look at people’s relationships to objects and the attributes those objects have. In the future, you’ll be able to trigger campaigns when you add or remove objects and relationships, making it easier to send one-to-many campaigns.
Before the end of 2023
These are things we’re going to do, but our designs haven’t yet taken shape.
For now, objects are one-to-many: you can relate an object to multiple people, but you can’t relate objects to objects, groups to groups. In the future, you’ll be able to relate objects to other objects. For example, imagine that you run fantasy leagues or an online gaming platform. You might set up a campaign when a game begins to send a game summary to the league managers, and a rules reminder to the players. In this case, a game is related to both league managers and players.Many-to-many relationships
Object-based conversion goals
When an account is paid, you should mark a conversion for the account rather than the person who paid it. In the future, you’ll be able to do just that.
Reference objects by type and id in liquid
Using objects in liquid will get easier. We’ll move away from referencing objects based on the time they were created in favor of referencing objects by their type and ID directly.
What we support today
While we describe what you can do with objects on this page, this table provides a quick reference for the ways in which you can use objects today.
Feature | API | UI | Additional Information |
---|---|---|---|
Create object types | * | The number you can enable depends on your plan. | |
Create objects | |||
Relate people to objects | |||
Relate objects to objects | |||
Import objects and/or relationships via reverse ETL integrations | N/A | ||
Import objects and/or relationships via CSV | |||
SegmentA group of people who match a series of conditions. People enter and exit the segment automatically when they match or stop matching conditions. people using relationships | N/A | ||
Trigger campaigns using relationships | N/A | You can relate a person to multiple objects matching a set of conditions, but they’ll only trigger a campaign journey for the first such relationship. See the section below for more information. | |
Trigger campaigns for each relationship | N/A | ||
LiquidA syntax that supports variables, letting you personalize messages for your audience. For example, if you want to reference a person’s first name, you might use the variable {{customer.first_name}} . support for objects in campaigns | N/A | See the section below for more information. | |
Use relationships in a newsletter audience | N/A | ||
LiquidA syntax that supports variables, letting you personalize messages for your audience. For example, if you want to reference a person’s first name, you might use the variable {{customer.first_name}} . support for objects in newsletters | N/A | See the section below for more information. | |
Use relationships in an API-triggered broadcast audience | N/A | ||
LiquidA syntax that supports variables, letting you personalize messages for your audience. For example, if you want to reference a person’s first name, you might use the variable {{customer.first_name}} . support for objects in API-triggered broadcasts | N/A | See the section below for more information. | |
Use relationships in transactional messages | |||
LiquidA syntax that supports variables, letting you personalize messages for your audience. For example, if you want to reference a person’s first name, you might use the variable {{customer.first_name}} . support for objects in transactional messages |
object_type_id
that does not exist, we’ll create it. We autocreate up to 15.Object Types
An object type defines the kind of one-to-many relationship you want to set, like Accounts, Employers, or Job Postings. The first three types appear in the side nav under People. If you have more than three, we’ll nest all of your object types under Custom Objects. Depending on your plan type, you can create 2 or more object types. In our API, we identify object types as integers starting at 1.


In the example above, the object type is Companies, which has 6 objects/individual companies.
Each object type gets its own object_type_id
, and you’ll set an object_id
for each object. An object_id
must be unique within a type, not across types. For example, object types 1
and 2
could each have an object identifier of a
.
Define a custom object type
Remember, an object type helps you differentiate groups of objects. We define the object_type_id
, but you define the object_id
. You’ll use this value to reference objects belonging to your new type.
Creating objects and types with our API
If you send an API request that includes an object_type_id
that doesn’t exist in your workspace, we’ll automatically create a new one for you up to 15 times. We’ll do the same for any object_id
that does not exist as well.
Go to Settings > Workspace Settings, and select Custom Objects.
Click Create Custom Object.
Choose your object type on the left or create your own on the right.
Give your object a Name and set the Singular form. In general, we expect that you’ll give objects a plural name (like “Accounts”); we simply use the Singular form to make better sense of your object name in prompts.
Liquid identifiers for objects
When you create a new object type, we automatically set the identifier for liquid. This is how you’ll reference objects of this type when personalizing messages with liquidA syntax that supports variables, letting you personalize messages for your audience. For example, if you want to reference a person’s first name, you might use the variable
{{customer.first_name}}
.. For example, if your object type is called Accounts, you’d reference objects in the format{{objects.accounts}}
. See Use objects in liquid for more information.Click Save.
API calls create objects and types if they don’t exist
If you send an API request that includes an object_type_id
or object_id
that doesn’t already exist, we’ll automatically create it for you.
Object types auto-created through our API are disabled by default, but you can enable them if you’re within your plan’s allotment.
If you add an object_type_id
or don’t provide one via API, we name it a type of animal. You can set a new Name and liquid tag under Settings > Workspace Settings > Custom Objects.
type exist?} b-->|yes|d{does object ID exist} b-.->|no|c[Create new
animal
object type]-.->d d-->|yes|e[update object
& relationships] d-.->|no|f[create new object] c-.->g[Go to UI to change
name and liquid tag]
Edit or rename an object type
You can change the name and liquid tag for object types. Changes to the Name and Singular Form affect what you see in Customer.io. Changing the liquid tag could affect your messages.
Is your liquid tag in use?
Messages that reference your liquid tag in active journeys will fail to send after you change your liquid identifier, unless you have a fallback. Before you change your object’s liquid tag, check the Usage field for the object type within Settings > Workspace Settings > Custom Objects. We advise against changing a liquid identifier that’s in use because drafted messages or those triggered between changing the identifier and changing the reference will fail to send.
- Go to Settings > Workspace Settings > Custom Objects.
- Click Object Name.
- Update the Object Type Name, Singular Form and/or Liquid Identifier. Then click Save.
Delete an object type
You can delete an object type through the UI, but not the API at this time.
Deleting an object type also deletes relationships
Deleting an object type permanently deletes all associated objects and relationships to people.
Check the Usage of the object type.
- You can delete a type when it is no longer in use in segments, campaigns, broadcasts, snippets, and email layouts.
If needed, adjust usage of your object type.
Select
Delete
at the top of the table.Confirm your selection.
You cannot re-use an object type id after it’s deleted.
If you create a new object type in the UI, it is automatically assigned a new integer. If you are creating object types programmatically, you must use a new id; we will not create a new object type if the id was previously used/deleted.
Enable/disable an object type
Your plan determines the number of enabled object types you can have. An enabled object type is one you can successfully reference in messaging and segments. You can view all enabled and disabled object types in the side menu.
You can create more than the number of object types allotted by your plan, but you can only enable the count that your plan allows. This grants you the flexibility to create objects and relationships while the object type is disabled so you can enable it shortly after disabling one you no longer need. Object types created over your plan allotment are disabled by default.
You can only disable a type if it is not referenced in any segments or messages.
Check the Usage of the object type.
- You can disable a type when it is no longer in use in segments, campaigns, broadcasts, snippets, and email layouts.
- You can enable a type as long as you have not surpassed the number of object types allowed in your plan.
If needed, adjust usage of your object type in segments and messages.
Object types auto-created through our API - those without an id or with an id that doesn’t exist yet - are disabled by default, but you can enable them if you’re within your plan’s allotment.
Create an object
Remember that an object type is the kind of non-people grouping that you want to track in Customer.io — like Companies, Online classes, or Accounts. An object is an individual thing — a single company, online class, or account — that you want to relate to one or more people.
You can create objects in several ways:
- via UI
- via API
- via reverse ETL integrations
- via Segment group calls
You can set relationships between objects and people programmatically, using the same methods above, as well as through our UI.
We don’t offer object-to-object relationships yet, but it’s on our roadmap.
Create an object in the UI
In the UI, you can create objects by going to your objects page(s) under People.
- Select your object type under People in the left hand nav.
- Set the
object_id
: this is the value you use when you set relationships between objects and people. - Set a
name
and any other attributes you want the object to contain. In general, we suggest that you set a name to help you recognize objects in the UI. Other 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. are values that you want to associate with people related to the object. - Click Save Changes to finish creating your object.
Now you can set relationships between your new object and people. For now, you’ll have to do that through our API.
Create an object in the API
Creating an object works just like identifying a person: you can send an identify
request to create a new object or update an existing object’s 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.. Any request that passes a new object ID will automatically create that object.
In general, it makes sense to create your custom object type first. But you can create a new type when you create a new object, simply by passing an object_type_id
that doesn’t already exist. If you’re not sure if a type exists, check in your workspace under People—if you see the object type you want to create, then pass that id.
You can create objects using the Track v2 or v1 APIs, but you can only set and update attributes using the v2 API.
In the v2 API, you’ll specify a type
and an action
. The object
type lets you modify objects, and the identify
action lets you create an object, set its attributes, and relate it to multiple people. You can create objects and set relationships with other action
types, but you can only set attributes through our API with the identify
action. (You can also update object attributes in the UI.)
curl --request POST \
--url https://track.customer.io/api/v2/entity \
--header "Authorization: Basic $(echo -n site_id:api_key | base64)" \
--header 'content-type: application/json' \
--data-raw '
{
"type": "object",
"identifiers": {
"object_type_id": "1",
"object_id": "acme"
},
"action": "identify",
"attributes": {
"name": "acme",
"bill_day": 15,
"monthly_due": 100.00,
},
"cio_relationships": [
{
"identifiers": {
"id": "42"
}
},
{
"identifiers": {
"email": "billing-contact@example.com"
}
}
]
}'
In our original Track API, you can set cio_relationships
to relate a person to one or more objects. If an object_type_id
or object_id
doesn’t exist, we’ll create it.
curl --request POST \
--url https://track.customer.io/api/v1/customer/billing-contact@example.com \
--header "Authorization: Basic $(echo -n site_id:api_key | base64)" \
--header 'content-type: application/json' \
--data-raw '
{
"plan": "basic",
"role": "accountant"
"cio_relationships": [
{
"identifiers": {
"object_type_id": "1",
"object_id": "acme"
}
},
{
"identifiers": {
"object_type_id": "1",
"object_id": "globex"
}
}
]
}'
An object’s attributes cannot exceed 100kb
You can keep setting relationships on an object, but the total attributes for an object can’t take up more than 100kb.
Import objects and relationships
You can sync objects (like companies, accounts, or online classes) and relate them to people as a part of our Reverse ETL database integrations - MySQL, BigQuery, Snowflake, and so on. This helps you add objects and relationships on a regular interval based on business logic and data that you store outside of Customer.io.
You can also import objects and relationships through Segment group calls.
Edit object attributes
You can set attributes for an object through our UI, or you can update them using the same API calls that you used to create objects.
To update object attributes in our UI:
- Select your object type from the left hand nav under People. Then click the object you want to modify.
- Click Edit Attributes.
- Set attributes for the object, and click Save.
Delete objects
You can delete objects in the UI or API. Deleting an object permanently removes the relationship from people.
Select your object type from the left hand nav.
Check the box next to each object you want to delete.
Select Delete at the top of the table, and confirm your selection.
To delete, you can also select the object name to navigate to its landing page. Then in the top right, select Options > Delete and confirm your selection.
Set relationships between objects and people
Create relationships between objects and people to segment users based on the groups they belong to and to personalize messages with object data.
You can create and remove relationships between objects and people through:
- object and people pages in the UI
- our track API
- our web sdk
- reverse ETL integrations
- our Segment integration
Set relationships in the UI
You can relate objects and people through our UI individually and in bulk. To remove relationships, visit an object or person page.
You can track the addition and removal of relationships in your Activity Log.
Set relationships in bulk
From the People page, you can relate multiple people to multiple objects within a single type.
- Go to the top right dropdown and select Add Relationships.
- Check the box next to each relevant person then continue to the next step.
- Choose which object type you want to target.
- Check each object you want to relate to the people you checked.
- Review and confirm.
You can also accomplish this from an Object Type landing page.
Set relationships individually
From a person’s page, you can add relationships to multiple objects.
- Go to People in the left hand nav.
- Select a person.
- Select Options > Add relationships in the top right.
- Select the Object Type you want to target.
- Check each object you want to set a relationship to.
- Review and confirm.
From an Object page, you can do the opposite - relate this one object to multiple people.
Delete relationships in the UI
You can delete relationships from the Relationships tab of a person or object page.
To delete relationships for a person:
- Go to a person’s page.
- Select the Relationships tab.
- Check the box beside each relationship you want to remove.
- Select Delete at the top of the table and confirm your action.


Set/delete relationships programmatically
You can relate objects to people in the same ways you can create objects through our API, our Web SDK, our reverse ETL integrations, and our Segment integration.
You can set relationships when you create an object (the identify
action) or later on, like when people enroll in a class or leave a company, with the add_relationships
or delete_relationships
actions.
You can also set relationships using our v1 API, but the examples below use our v2 API, which is more flexible and provides the ability to send multiple requests in the same call.
You can set relationships on an object or a person—determined by the type
parameter. Specify an object if you want to set relationships with multiple people; specify a person if you want to relate them to multiple objects.
curl --request POST \
--url https://track.customer.io/api/v2/entity \
--header "Authorization: Basic $(echo -n site_id:api_key | base64)" \
--header 'content-type: application/json' \
--data-raw '
{
"type": "object",
"identifiers": {
"object_type_id": "1",
"object_id": "acme"
},
"action": "add_relationships",
"cio_relationships": [
{
"identifiers": {
"id": "42"
}
},
{
"identifiers": {
"email": "billing-contact@example.com"
}
}
]
}'
curl --request POST \
--url https://track.customer.io/api/v2/entity \
--header "Authorization: Basic $(echo -n site_id:api_key | base64)" \
--header 'content-type: application/json' \
--data-raw '
{
"type": "person",
"identifiers": {
"email": "billing-contact@example.com",
},
"action": "add_relationships",
"cio_relationships": [
{
"identifiers": {
"object_type_id": "1",
"object_id": "acme"
}
},
{
"identifiers": {
"object_type_id": "1",
"object_id": "globex"
}
}
]
}'
If you use our Web SDK, you can set relationships using the identify
function. Your JavaScript snippet must include the line t.setAttribute('data-use-array-params', 'true');
, or you’ll receive an error when you attempt to set relationships this way.
_cio.identify({
id: 'userid_34',
email: 'customer@example.com',
cio_relationships: {
action: "add_relationships",
relationships: [
{
identifiers: {
object_type_id: "1",
object_id: "acme"
}
}
]
}
});
Send fewer requests with the batch endpoint
You can use our /v2/batch
endpoint to send multiple requests in the same payload.
Find object relationships
You can find relationships from the Relationships tab of an object or person page.
To see who is related to an object:
Select an Object Type under People in the side menu.
Select an Object.
Click the Relationships tab to view a list of related people.
Use an object in a segment
You can create object-oriented segmentsA group of people who match a series of conditions. People enter and exit the segment automatically when they match or stop matching conditions. on the Segments page, or when you create campaigns and newsletters. Learn more about how relationship-based segments work in campaigns.
- Go to Segments and click Create Segment.
- Give your segment a Name and a Description, and click Create Data-Driven Segment.
- Under Add condition or group, select Relationship and set a condition to Relationship to
your object type
exists. - (Optional) you can refine your selection by clicking Refine and select an object-based attribute condition. For example, you might want to limit a newsletter segment based on a
country
orplan_name
attribute. - When you’re done, click Save Changes.
Now you can use your segment in newsletters or to trigger campaigns.
Relationship-based segments in campaigns
People enter segment-triggered campaigns when they join (or leave) a segment. But when you create a relationship-based segment, a person only joins the segment for their FIRST relationship to an object matching your criteria. Their segment membership won’t change on subsequent relationships. This means that a person will only trigger a campaign for the first relationship matching your segment criteria. For now, you cannot trigger a campaign for each relationship matching your segment criteria.
For example, imagine that you have a segment of people related to online classes, and you use that segment to trigger a campaign:
- When a person signs up for their first online class, they’ll join the segment and enter the campaign.
- When they sign up for another online class, they won’t trigger the campaign again because their segment membership didn’t change!
In this example, a person would only re-join the segment if they unenrolled from all their classes, causing them to leave the segment, and then re-enrolled in a class later.
to person)-->b{is this the first
relationship?} b-->|yes|c(person joins
segment)-->e(Person enters
campaign) b-.->|no|d(person does not
enter campaign)
Exit Conditions follow these same principles: a person won’t leave a segment (causing them to exit a campaign) until they’re no longer related to any objects matching your segment criteria.
from person)-->b{is this the only
relationship?} b-->|yes|c(person leaves
segment)-->e(Person exits
campaign) b-.->|no|d(person remains
in campaign)
You cannot backfill relationships
We don’t have a concept of historical relationships in Customer.io—at least not yet. For example, a person might have joined a company several years ago, but it will appear that they only recently joined the company when you set their relationship in Customer.io.
Because you can’t backfill relationships, you should be careful when using relationship-based segments to trigger your campaigns. For example, if you want to send a welcome campaign for new employees of a company, and you relate people to the company after you set up your campaign, you may inadvertently trigger a welcome campaign for those people.
Use objects in liquid
You’ll reference objects in liquid by their type. By default, this means you’d use {{objects.companies}}
. But, if your objects were called something like Online Classes, you’d use {{objects.online_classes}}
. We’ve provided some examples to help you take advantage of objects below.
New to JSON?
Objects in Customer.io use JSON dot notation; if you’re not familiar with JSON, we have a quick primer to help you understand how it works.
Keep in mind:
- You can reference the most recent 10 objects associated with a person for EACH object type.
- You’ll reference objects in the order that they’re created.
For example, imagine that you created two online_classes
, English Literature and Calculus 1A, in that order. If a person enrolled in both classes, you’d reference the person’s English enrollment with {{objects.online_classes[0]}}
and the person’s calculus class with {{objects.online_classes[1]}}
—even if they signed up for the calculus class first!
Note that {{objects.online_classes[0]}}
would show all of the 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. for the English class! If you wanted to reference the class name, you’d use something like [[objects.online_classes[0].name}}
Using objects in liquid will get easier
We realize that it’s not ideal that you’d have to remember the order in which you created objects. In the future, you’ll be able to reference objects by their type and ID directly.
Liquid examples
The following examples imagine that you relate people to “online classes”, similar to the example in the section above.
Check if a person is related to objects
{% if objects.online_classes | size == 0 %}
This person doesn't have any classes.
{% else %}
This person is enrolled in at least one class.
{% endif %}
Loop through classes: the following liquid displays information for every class related to a person.
{% for class in objects.online_classes %}
Your {{class.name}} begins on {{class.date}} at {{class.time}}.
{% endfor %}
Reference individual object properties
Your {{objects.online_classes[0].name}} begins on {{objects.online_classes[0].date}}.
Are you ready?