> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unifygtm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Relate objects

> Connect records across objects with references.

## Overview

Available only on Business plans.

Reference attributes connect records across objects. For example, a person's
company reference identifies the company they work for. Following that reference
gives you access to the company's attributes.

You can use related data in [filters](https://docs.unifygtm.com/reference/filter-builder.md), including
filters that determine which records enter a play. You can also follow references
in [template variables](https://docs.unifygtm.com/reference/sequences/personalization/template-variables.md)
to personalize content with values from related records.

## How references work

A reference points to a record in another object. When you create a relationship,
Unify adds a reference attribute on each object so the connection can be followed
in both directions.

Each side can reference one or many records:

| Relationship | How it works |
| - | - |
| One to many | A record on one side can relate to several records on the other. A company can have many people, while each person has one company. |
| Many to many | Records on both sides can have several related records. A project can involve several people, and a person can participate in several projects. |

“One” means at most one related record. In the relationship editor, at least
one side must allow many records.

The attributes define the relationship between objects. Values supplied through
an integration or the API connect the individual records.

## Create a relationship

Both objects must exist before you create the relationship.

**1. Add a reference attribute**

Open an object in [**Settings → Data management**](https://app.unifygtm.com/dashboard/settings/data/data-management).
In **Attributes**, click **Create attribute** and choose **Relationship**
as the type.

**2. Configure both sides**

Select the related object. Give each side an attribute name describing the
records it references, then choose whether it can reference one or many
records. Each attribute also has an API name that is fixed after creation.

The relationship editor with an attribute on each object and controls for one or many related records.

**3. Create the relationship**

Click **Create attribute**. The two objects now have reference attributes
that your integration or API can populate with related records.

For programmatic setup, use the Data API's
[Create attribute](https://docs.unifygtm.com/developers/api/data/attributes/create.md) endpoint. To connect
individual records, see the [Upsert record examples](https://docs.unifygtm.com/developers/api/data/records/upsert.md#examples).

## Edit relationships

You can rename custom reference attributes. Their API names and the related
object are fixed after creation.

The editor lets you expand a reference from one record to many. This affects
where it can be used: template variables, for example, can only follow references
to a single record. A reference that allows many records cannot be narrowed to one.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.