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:

  1. Go to Companies in the side menu to get started.
  2. You can create objects and relate them to people using our new v2 API or Segment’s group calls.
  3. 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.

companies your audience might belong to
companies your audience might belong to

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.

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[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.

flowchart LR subgraph UI direction TB a[1. create object type] d[4. create segments] e[5. trigger newsletter] end subgraph API direction TB b[2. create object] c[3. Associate object with people] f[5. trigger broadcast] end a-->b b-->c c-->d d-->e d-->f
FeatureAPIUIAdditional 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
*There’s no call/payload to create a new object type. If you send a request to our API with a 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

Support for objects in campaigns

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.

Full control over object relationships and object types in the UI/API

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.

Before the end of 2023

These are things we’re going to do, but our designs haven’t yet taken shape.

Many-to-many relationships

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.

Support for multiple object types

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.

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.

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.

companies your audience might belong to
companies your audience might belong to

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.

set the name and singular form for your object
set the name and singular form for your object

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.

  1. Go to Settings > Workspace Settings, and select Custom Objects.
    the list of object types
    the list of object types
  2. Click Create Custom Object.
  3. 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.
    set the name and singular form for your object
    set the name and singular form for your object
  4. 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.

flowchart LR a[API request]-->b{Does object
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.

  1. Go to Settings > Workspace Settings, and select Custom Objects.
  2. Click Edit for the object type you want to manage.
  3. 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:

  1. Go to and select the object you want to modify.
    find your object and see all its attributes
    find your object and see all its attributes
  2. Click Edit Attributes.
  3. Set attributes for the object, and click Save.
    modify your object's attributes
    modify your object's attributes

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 , selecting an object, and going to the Relationships tab.

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.

  1. Go to Broadcasts and click Create Broadcast.
  2. Give your newsletter a Name, select the Newsletter option, and click Create Broadcast.
  3. In the Recipients step, make sure People matching conditions is selected and click Add new segment condition.
  4. In the Segments dropdown, click Create new data-driven segment.
  5. Under Add condition or group, select Relationship and set a condition to Relationship to your object type exists.
  6. (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 or plan_name attribute.
set up a segment of people related to an object
set up a segment of people related to an object

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?
Copied to clipboard!
Is this page helpful?