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.

 Check out our plans and how we bill to learn more about object pricing.

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

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]

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. Create objects and relate them to people in the UI or programmatically.
  3. 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.

Improvements to working with objects using liquid

Define the objects you want to reference in liquid instead of being limited to the 10 most recently added per type.

Objects in workflow actions

Add workflow actions for objects like Create or Update Object and Branching based on object or relationship attributes. Query objects similar to how you can query collections to, for instance, send a newsletter with concert listings to people in a specific city.

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.

FeatureAPIUIAdditional 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 integrationsN/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 relationshipsN/A
Trigger campaigns using relationshipsN/AYou 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 relationshipN/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 campaignsN/ASee the section below for more information.
Use relationships in a newsletter audienceN/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 newslettersN/ASee the section below for more information.
Use relationships in an API-triggered broadcast audienceN/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 broadcastsN/ASee 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
*There’s no call/payload to create a new object type. If you send a request to our API with an 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.

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

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.

  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. Choose your object type on the left or create your own on the right.

    choose a pre-determined object type on the left or create a new type on the right
    choose a pre-determined object type on the left or create a new type on the right

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

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

     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.

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

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

  1. Go to Settings > Workspace Settings > Custom Objects.
  2. Click Object Name.
  3. 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.

  1. Go to Settings > Workspace Settings > Custom Objects.

  2. Check the Usage of the object type.

    1. You can delete a type when it is no longer in use in segments, campaigns, broadcasts, snippets, and email layouts.
    There is a field to the right of every object type that reveals how many times an object type is referenced in liquid for campaigns, broadcasts, and segments.
    There is a field to the right of every object type that reveals how many times an object type is referenced in liquid for campaigns, broadcasts, and segments.
  3. If needed, adjust usage of your object type.

  4. Check the box beside each object type you want to delete.

    The checkbox to the left of Accounts is checked. A delete button appears at the top of the table.
    The checkbox to the left of Accounts is checked. A delete button appears at the top of the table.

  5. Select Delete at the top of the table.

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

  1. Go to Settings > Workspace Settings > Custom Objects.

  2. Check the Usage of the object type.

    1. You can disable a type when it is no longer in use in segments, campaigns, broadcasts, snippets, and email layouts.
    2. You can enable a type as long as you have not surpassed the number of object types allowed in your plan.
    There is a field to the right of every object type that reveals how many times an object type is referenced in liquid for campaigns, broadcasts, and segments.
    There is a field to the right of every object type that reveals how many times an object type is referenced in liquid for campaigns, broadcasts, and segments.
  3. If needed, adjust usage of your object type in segments and messages.

  4. Toggle Enable/Disable for the object type.

    One object type is enabled and unable to be disabled because it's in use. Another object type is disabled and can be enabled because it's not in use.
    One object type is enabled and unable to be disabled because it's in use. Another object type is disabled and can be enabled because it's not in use.

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:

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.

  1. Select your object type under People in the left hand nav.
  2. Set the object_id: this is the value you use when you set relationships between objects and people.
  3. 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.

     You cannot use relationship as an object attribute name. relationship is reserved for referencing relationship attributes (coming Oct 2023) in Liquid.

  4. Click Save Changes to finish creating your object.
    create an object in the UI
    create an object in the UI

Now you can set relationships between your new object and people.

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.

 You cannot use relationship as an object attribute name. relationship is reserved for referencing relationship attributes (coming Oct 2023) in Liquid.

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 or remove 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. Go here to learn how to edit object attributes through Segment group calls.

In our Track v2 API, use attributes to modify an object’s data. Set an attribute value to null or an empty string to remove attributes.

 You cannot use relationship as an object attribute name. relationship is reserved for referencing relationship attributes (coming Oct 2023) in Liquid.

To update object attributes in our UI:

  1. Select your object type from the left hand nav under People. Then click 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 or click the trash can icon to remove attributes. Then click Save.
    modify your object's attributes
    modify your object's attributes

Delete objects

You can delete objects in the UI, API or through Segment group calls.

Deleting an object permanently removes the relationship from people.

To delete objects in the UI:

  1. Select your object type from the left hand nav.

  2. If applicable, filter by object attributes to locate the ones you want to remove. Check the box next to each object you want to delete.

    Two objects are checked. A delete button appears at the top of the table.
    Two objects are checked. A delete button appears at the top of the table.
  3. 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.

  1. Go to the top right dropdown and select Add Relationships.
  2. Check the box next to each relevant person then continue to the next step.
  3. Choose which object type you want to target.
  4. Check each object you want to relate to the people you checked.
  5. 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.

  1. Go to People in the left hand nav.
  2. Select a person.
  3. Select Options > Add relationships in the top right.
  4. Select the Object Type you want to target.
  5. Check each object you want to set a relationship to.
  6. 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:

  1. Go to a person’s page.
  2. Select the Relationships tab.
  3. Check the box beside each relationship you want to remove.
  4. Select Delete at the top of the table and confirm your action.
A view of the relationships tab with multiple objects selected and the delete button visible above the table.
A view of the relationships tab with multiple objects selected and the delete button visible above the table.

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:

  1. Select an Object Type under People in the side menu.

  2. Select an Object.

  3. Click the Relationships tab to view a list of related people.

    Two people are associated with object Acme Corp.
    Two people are associated with object Acme Corp.

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.

  1. Go to Segments and click Create Segment.
  2. Give your segment a Name and a Description, and click Create Data-Driven Segment.
    give your segment a name and description
    give your segment a name and description
  3. Under Add condition or group, select Relationship and set a condition to Relationship to your object type exists.
    set up a segment of people related to an object
    set up a segment of people related to an object
  4. (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.
  5. 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.

flowchart LR a(add relationship
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.

flowchart LR a(remove relationship
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?
Copied to clipboard!