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.

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.

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.

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.

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

Before the end of 2023

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

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.

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

   

   
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.

   

   
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.

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.

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": [
        {
            "object_type_id": "1",
            "object_id": "acme"
        },
        {
            "object_type_id": "1",
            "object_id": "globex"
        }
    ]

}'

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

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.

   

   
2. Click Edit Attributes.
3. 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 , 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.

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.

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

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?