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

> Link records across objects with relationship attributes.

export const ThemedImageFrame = ({lightSrc, darkSrc, alt, caption}) => <Frame caption={caption}>
    <div className="block w-full dark:hidden">
      <OptimizedImage className="w-full" src={lightSrc} alt={(alt ?? caption) ?? ""} />
    </div>
    <div className="hidden w-full dark:block">
      <OptimizedImage className="w-full" src={darkSrc} alt={(alt ?? caption) ?? ""} />
    </div>
  </Frame>;

export const PlanAvailability = ({plans}) => <aside aria-label="Plan availability" className="not-prose my-6 flex items-start gap-3 rounded-xl border border-zinc-200 bg-zinc-50 px-4 py-3 text-sm leading-6 text-zinc-700 dark:border-zinc-700 dark:bg-white/5 dark:text-zinc-300">
    <svg aria-hidden="true" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" className="mt-1 shrink-0">
      <path d="m12 3 9 5-9 5-9-5 9-5Z" />
      <path d="m3 12 9 5 9-5M3 16l9 5 9-5" />
    </svg>
    <span>Available only on {plans} plans.</span>
  </aside>;

## Overview

<PlanAvailability plans="Business" />

A relationship attribute links a record to records in another object. For
example, a subscription can belong to one company, while a company can have many
subscriptions. This lets the subscription keep its own fields while remaining
connected to the company it describes.

Creating the attribute defines which records can be linked. Your integration or
API must then supply the links between individual records.

## Decide how many records can be linked

For each direction, choose how many related records a single record can have.

| Relationship | Example |
| - | - |
| One to many | One company has many subscriptions; each subscription has one company. |
| Many to many | A person can use several product workspaces, and each workspace can have several people. |

The same company–subscription relationship is many to one when read from the
subscription side. Read both directions before saving. One means at most one
related record; many allows several. At least one direction must allow many records.

## Create the relationship

Start with both objects already defined. This example links a subscription to a
company.

<Steps>
  <Step title="Choose the relationship type">
    Open the subscription object in [Settings → Data management](https://app.unifygtm.com/dashboard/settings/data/data-management).
    In **Attributes**, click **Create attribute**, then choose **Relationship**
    as the **Attribute type**.
  </Step>

  <Step title="Name both sides">
    Under **Configure relationship**, select the company object on the right.
    Name the attribute on the subscription `Company`, and name the attribute on
    the company `Subscriptions`. Review both generated API names.

    These names describe what someone will find when reading each object:
    the company for a subscription, and the subscriptions for a company.
  </Step>

  <Step title="Set the relationship size">
    Set the subscription's direction to **one** company and the company's
    direction to **many** subscriptions. Review the two **has** statements
    together to check that they describe your data.

    <ThemedImageFrame lightSrc="/images/reference/objects/subscription-relationship-light.png" darkSrc="/images/reference/objects/subscription-relationship-dark.png" alt="A relationship linking each subscription to one company and each company to many subscriptions." />
  </Step>

  <Step title="Save and populate the relationship">
    Click **Create attribute**. Check the relationship attributes on both objects.
    Your integration or API can now link individual subscription records to
    their company records.

    [Inspect a record](/reference/objects/inspect-records) after sending data to
    confirm that the expected relationship is populated.
  </Step>
</Steps>

## Change an existing relationship

The related object and API names are fixed after creation. The editor can expand
a relationship from one to many, but cannot narrow many to one.
Review the effect on the workflows and integrations that consume the relationship
before expanding it.

Older reference attributes may link in one direction only. The editor shows
these with a single relationship arrow.

In the API, relationship attributes use the reference type. See
[Create an attribute with the API](/developers/api/data/attributes/create) for
programmatic setup.


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