> This page is part of the [Customer.io documentation](https://docs-customerio.netlify.app). For the complete index, see [llms.txt](https://docs-customerio.netlify.app/llms.txt).
> Last updated: December 31, 2025

# Relationships

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

While you can relate objects to people, you can’t relate objects to objects. If this is functionality you need, please [share your use case with us](mailto:win@customer.io).

## Set relationships in the UI[](#relationships-ui)

You can relate objects and people through our UI individually and in bulk. [To remove relationships](#delete-relationships-in-the-ui), visit an object or person page.

You can track the addition and removal of relationships in your [Activity Log](https://fly.customer.io/workspaces/last/journeys/activity_logs/identified).

### Set relationships in bulk[](#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.  Check each object you want to relate to the people you checked.
4.  (Optional) Add relationship attributes—information that defines how the person is related to the object.
5.  Review and confirm.

You can also accomplish this from an **Object Type** landing page.

### Set relationships individually[](#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[](#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.](https://docs.customer.io/images/relationships-delete.png)](#99edfc18251ead3a5c5ccde82743adc7-lightbox)

## Set/delete relationships programmatically[](#setdelete-relationships-programmatically)

You can relate objects to people in the same ways you can create objects through [our API](/integrations/api/track/), our [Web SDK](/integrations/sdk/web/identify/#relate-people-to-objects), our [reverse ETL integrations](/integrations/data-in/connections/reverse-etl/about-reverse-etl/), and our [Segment integration](/journeys/segment-destination/#segment-group-calls).

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](/integrations/api/track/#operation/identify), but the examples below use our v2 API, which is more flexible and provides the ability to send [multiple requests in the same call](/integrations/api/track/#operation/batch).

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.

 Object to multiple people

#### Object to multiple people[](#Object to multiple people)

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

 Person to multiple objects

#### Person to multiple objects[](#Person to multiple objects)

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

 Person to objects (JS)

#### Person to objects (JS)[](#Person to objects \(JS\))

If you use our [Web SDK](/integrations/sdk/web/), 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.

```javascript
_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.

### Set relationship attributes with the Pipelines API[](#set-relationship-attributes-with-the-pipelines-api)

You can set relationship attributes using the [Pipelines API](/integrations/api/cdp/) and most of our [integration libraries](/integrations/catalog/).

You can set relationship attributes in either a `group` call or an `identify` call. In both cases, you’ll put relationship attributes in the `traits.relationshipTraits` object.

 Group

#### Group[](#Group)

```json
{
    "userId": "student-1234",
    "groupId": "math101-2024",
    "traits": {
        "object_type_id": "2",
        "relationshipTraits": {    
            "dues_paid": true,
            "class_complete": true,
            "grade": "A-"
        }
    }
}
```

 Identify

#### Identify[](#Identify)

```json
{
    "userId": "student-1234",
    "traits": {
        "object_type_id": "2",
        "objectId": "math101-2024",
        "relationshipTraits": {
            "dues_paid": true,
            "class_complete": true,
            "grade": "A-"
        }
    }
}
```

 We default `object_type_id` to `1`

You don’t need to define the `object_type_id`, but we default to `1`—your first object type—if you don’t include it.

## Update relationship attributes[](#update-relationship-attributes)

Just like you can add attributes to objects and people, you can also add attributes to relationships between objects and people. For instance, if someone is related to three account objects, you could set an attribute like `role` on their relationships to describe how they’re related to each account—like an owner on one account and a member of the others.

To set relationship attributes between a person and an object:

1.  On a person’s profile, select the *Relationships* tab.
    
    [![relationships-tab.png](https://docs.customer.io/images/relationships-tab.png)](#5827e53afc698de4816b496f47ffea94-lightbox)
    
2.  Click on the attribute count.
    
    [![relationship-attributes-person-page.png](https://docs.customer.io/images/relationship-attributes-person-page.png)](#950ff1798a971ffab25b83c034fb19f2-lightbox)
    
3.  Click **Create New Attribute** on the right hand panel.
4.  Enter the attribute name and value for the person.
5.  Click **Save** at the bottom of the panel.

You can also accomplish the above through the *Relationships* tab of an object’s page.

[![An object page called Acme Corp is selected. A right-hand panel shows the ability to create a new relationship attribute.](https://docs.customer.io/images/relationship-attributes-object-page.png)](#beda2f1cc14e9b9464f76167ebe3118e-lightbox)

Use our Track v1 or v2 APIs to set relationship attributes programmatically:

*   [v1: Add or update a customer](/integrations/api/track/#section/Overview)
*   [v2: Make a single request](/integrations/api/track/#operation/entity)
*   [v2: Send multiple requests](/integrations/api/track/#operation/batch)

Now, you can create a [data-driven segment](/journeys/data-driven-segments/#segment-based-on-object-relationships) or trigger a campaign based on relationship attributes.

### Reserved attributes[](#reserved-attributes)

Customer.io has reserved these object and relationship attributes to support core functionality in the platform:

Attribute

Purpose

Required

Data Format

`cio_object_id`

A unique, immutable identifier for objects provided by Customer.io. If this does not yet exist in your workspace, we create a new object.

When importing by `cio_object_id`

`object_id`

A unique identifier for objects. If the `object_id` does not yet exist, we create a new object.

When importing by `object_id`

Our default `id` limit is set to 150 characters. All valid UTF characters are allowed.

`objectId`

String

An analog for `object_id` in some Customer.io integrations.

`relationship`

Used to reference relationships to objects. Cannot be used as the name of an **object** attribute.

[To reference relationships in liquid](/journeys/objects-in-liquid/#relationship-attribute)

`_relationship`

Used in relationship-triggered campaigns to reference audience members who did not trigger the campaign. Cannot be used as the name of a **customer** attribute.

[To reference relationships in liquid](/journeys/objects-in-liquid/#audience-attribute)

`created_at`

Unix timestamp when the object was first created. Used when listing objects in the UI, for example.

No

Unix timestamp

`timezone`

The user’s time zone. Used for [sending localized messages](/journeys/timezone-match/).

No

[Region Format](/journeys/example-timezones/#region-format)

## Find object relationships[](#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.](https://docs.customer.io/images/object-relationships.png)](#1f9c23e88eda3cd37bcecc3cb67f3d18-lightbox)
    

## Filter for objects without relationships[](#filter-for-objects-without-relationships)

Filtering for objects without relationships can help you determine if you have unused objects. Since objects count towards billing, it’s best practice to review them monthly and [delete the objects](/journeys/objects-create/#delete-objects) you don’t need.

Select your object type in the left-hand navigation, and then click **Objects without relationships** to review them.

[![A list view of objects with the filter applied for the object type Salesforce Accounts.](https://docs.customer.io/images/objects-without-relationships.png)](#007b24eb009cda88e097a3dabd01a35f-lightbox)

Learn more about [how billing works](/accounts-and-workspaces/how-we-bill/) and how to [reduce billing overages](/accounts-and-workspaces/reduce-billing-overages/).