Objects
New PremiumThis feature is available on our Premium and Enterprise plans.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.
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.
- You can create objects and relate them to people using our new v2 API or Segment’s
group
calls. - You can use objects in Segments and Newsletters for now. We’ll add support for campaigns soon.
See the flowchart in this section for more about the general order of operations in creating types, objects, setting relationships, and sending messages.
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—like their name, the date they were created in your workspace, 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]
Where you can use objects
Because this is a new feature, you can’t use objects everywhere in the system just yet. For now, you can create an object in the user interface, but you can’t associate an object with a person in the UI. You’ll need to do that in the API.
The flowchart below shows the general order in which you’ll create objects, set relationships between people and objects, and use them in newsletters. However, our API is incredibly flexible. You can create a new object type, object ID, and set relationships all with a single identify
request.
Feature | API | UI | Additional Information |
---|---|---|---|
Create object types | * | Limted to one object “type” for now | |
Create objects | |||
Set object relationships | |||
Use objects in campaigns | |||
Use objects in newsletters | |||
Use objects in transactional messages |
object_type_id
that does not exist, we’ll create it. You can also send Segment.io’s group
calls
Objects in Customer.io are analogous to “groups” in Segment. You can send segment group
calls to create objects and relate them to your audience.
Planned updates for this feature
Objects are a new feature, but it’s one you can be confident in. We want you to know that 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
Objects will be able to trigger campaigns, sending people related to an object through the campaign. For example, if you manage accounts, you could send a campaign that encourages your non-premium accounts to upgrade when it’s time to renew their contract. We recognize that it’s inconvenient you can only set relationships via our API while you use objects and object-relationships in our UI. In the near future, you’ll be able to do everything from the UI or API—whichever you prefer.Support for objects in campaigns
Full control over object relationships and object types in the UI/API
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. You’ll be able to support different kinds of grouping mechanisms in your workspace—companies, accounts, online classes, and whatever other kinds of groups your audience might belong to. 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.Many-to-many relationships
Support for multiple object types
Object-based conversion goals
Object Types
An object type defines the kind of one-to-many relationship you want to set, like Accounts, Employers, or Job Postings. Each type appears in the UI under People. For now, you can only have one type of object; we default to Companies. In the API, it’s value is 1
.


In the future, object types will help you differentiate between different kinds of objects. For example, you might have different types for Employers and Job Postings.
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. In the future, when you can have multiple types, this might mean that you have different object types for teachers and students, but could set the same object_id
for both—so it’s easy to associate the two.


Define a custom object type
Remember, an object type helps you differentiate between different kinds of objects. Each object type shows up in the menu under People. When you create an object, we’ll give it a object_type_id
. You’ll use that value to reference objects belonging your new type. Remember, for now you can only have one type of object. We plan to support more types in the near future.
You can also create new types with our API
If you send an API request that includes an object object_type_id
or object_id
that doesn’t already exist, we’ll automatically create it for you.
- Go to Settings > Workspace Settings, and select Custom Objects.
- Click Create Custom Object.
- Give your object a Name and set the Singular form. In general, we expect that you’ll give objects a plural name (like “Companies”); we simply use the Singular form to make better sense of your object name in prompts.
- Click Save.
Note that 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 Companies, you’d reference objects in the format {{objects.companies}}
. See Use objects in liquid for more information.
API calls create objects and types if they don’t exist
If you send an API request that includes an object object_type_id
or object_id
that doesn’t already exist, we’ll automatically create it for you.
When you use a new object_type_id
with our API, we assume you’re creating companies
by default. So, if you add a new object_type_id
that you haven’t created in the UI, your new type will be called Companies, the liquid name is companies
, and the singular type is Company. You can set a new Name for types created this way under Settings > Workspace Settings > Custom Objects, but you can’t update the way you’ll reference objects of this new type with liquid—you’ll always reference your new object type as object.companies
.
type exist?} b-->|yes|d{does object ID exist} b-.->|no|c[Create new
companies
object type]-.->d d-->|yes|e[update object
& relationships] d-.->|no|f[create new object] c-.->g[Go to UI and change
name of new type]
Edit an object type
An object type can be associated with people in your workspace. To prevent issues with active relationships, you cannot change an object type’s identifier or delete an object that’s currently associated with people. You can only update an object type’s name and singular form—things that affect how your objects appear in Customer.io.
- Go to Settings > Workspace Settings, and select Custom Objects.
- Click Edit for the object type you want to manage.
- Update the Object Name and/or Singular Form and click Save.
Create an object
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—like their name, the date they were created in your workspace, etc. Use attributes to target people and personalize messages.. But, 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 (which we automatically call companies) when you create a new object, simply by passing a 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 you’re all set.
You can create objects using the Track v2 or v1 APIs, but you can only set and update attributes using the v2 API. You cannot yet create objects from our UI, JavaScript snippet, mobile SDKs or other libraries. We plan to add more support for objects as we continue working on this feature.
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 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": [
{
"object_type_id": "1",
"object_id": "acme"
},
{
"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.
Set relationships between objects and people
For now you can only associate objects with people through our API; you cannot set object-to-object relationships.
You can set relationships 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": [
{
"object_type_id": "1",
"object_id": "acme"
},
{
"object_type_id": "1",
"object_id": "globex"
}
]
}'
Send fewer requests with the batch endpoint
You can use our /v2/batch
endpoint to send multiple requests in the same payload.
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:
- Go to
and select the object you want to modify. - Click Edit Attributes.
- Set attributes for the object, and click Save.
Find object relationships
You can look up a person in our API to see which objects an individual person is related to. You can also look up an object in our UI and see who it’s related to by going to
Use an object in a segment or newsletter
For now, you can only use objects to segment newsletter audiences. You can create your 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 while setting up a newsletter, but you can’t use that segment in campaigns. In the future, you’ll be able to use objects in campaigns and API-triggered broadcasts.
- Go to Broadcasts and click Create Broadcast.
- Give your newsletter a Name, select the Newsletter option, and click Create Broadcast.
- In the Recipients step, make sure People matching conditions is selected and click Add new segment condition.
- In the Segments dropdown, click Create new 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.


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.
You can reference the most recent 10 objects associated with a person. To use the most recent object assigned to a person, you’d use {{objects.companies[0]}}
. For example, imagine that a person in your workspace was related to two online_classes
, English Literature and Calculus 1A, in that order. You would reference the person’s English enrollment with {{objects.online_classes[0]}}
and the person’s calculus class with {{objects.online_classes[1]}}
.
Note that {{objects.online_classes[0]}}
would show all of the attributesA key-value pair that you associate with a person—like their name, the date they were created in your workspace, 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 relate objects to people in this initial release. 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?