20

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.

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.

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.

Before the end of 2023

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

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.

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.

1. Go to Settings > Workspace Settings, and select Custom Objects.

   

   

2. Click Create Custom Object.

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

   

   

    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.

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.

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.

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.

   

   

3. If needed, adjust usage of your object type.

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

   

   

5. Select Delete at the top of the table.

6. Confirm your selection.

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.

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.

   

   

3. If needed, adjust usage of your object type in segments and messages.

4. Toggle Enable/Disable for the object type.

   

   

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.

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.

   

   

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.

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"
            }
        }
    ]
}'

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"
            }
        }
    ]

}'

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.

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.

   

   
2. Click Edit Attributes.
3. Set attributes for the object or click the trash can icon to remove attributes. Then click Save.

   

   

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.

   

   

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.

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"
      }
    }
  ]
}'

_cio.identify({
  id: 'userid_34',
  email: 'customer@example.com',
  cio_relationships: {
        action: "add_relationships",
        relationships: [
            {
                identifiers: {
                    object_type_id: "1",
                    object_id: "acme"
                }
            }
        ]
    }
});

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.

   

   

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.

   

   
3. Under Add condition or group, select Relationship and set a condition to Relationship to your object type exists.

   

   
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.

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.

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.

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

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?