Custom Relationships

Define no-code, bidirectional links between any two object types — with cardinality, scoping, and typed pivot fields.

Overview

Custom Relationships let you define and manage links between any two object types — Contacts, Content Instances, Documents, Orders, and more — without writing code or changing schemas. A relationship is a single definition with two sides, each with its own title, alias, object type, optional scope, and cardinality. From those two sides CXF derives the relationship’s cardinality type and exposes the link on both objects. For the mental model, see Core concepts.

Relationships are bidirectional: each side is addressed by its own alias, so the same link reads naturally from either object.

Where to find it

Relationship definitions are managed from Templates and Profiles. Once defined, you attach and detach the related objects from the Relationships tab on a record.

Properties

A definition holds both sides, suffixed _1 and _2:

Property	Type	Required	Description
title_1 / title_2	string	Yes	Human-readable label for each side.
alias_1 / alias_2	string	Yes	Identifier for each side (snake_case) — how you address it. Unique across relationships, and the two sides must differ.
object_type_1 / object_type_2	enum	Yes	The object type on each side.
cardinality_1 / cardinality_2	enum	Yes	one or many on each side — together they form the cardinality type.
content_type_1 / content_type_2	string	Conditional	Required when that side’s object type is content_instances.
template_id_1 / template_id_2	reference	No	Restrict the side to a Template (see Scoping).
profile_id_1 / profile_id_2	reference	No	Restrict the side to a Profile.
pivot_fields_config	array	No	Typed extra fields on the link — many_many only (see Pivot fields).

Cardinality

Each side is one or many; the pair forms the relationship’s cardinality type:

cardinality_1	cardinality_2	Type	Example
one	one	one_one	A Contact ↔ a single Profile record
one	many	one_many	A Customer → many Orders
many	one	many_one	Many Orders → one Customer
many	many	many_many	Students ↔ Courses

Only these four combinations are valid.

Pivot fields

A many_many relationship can carry pivot fields — extra values stored on the link itself (not on either object). Each is defined with a slug and a type (text, number, or boolean), and is validated when you attach or update a link.

Pivot fields are allowed on many_many relationships only.

Scoping

Each side is either global or scoped:

• Global — template_id and profile_id are unset; the side applies to all records of its object type.
• Scoped — restricted to a specific Template or Profile, so only those records can participate.

Attaching and detaching

You link records by attaching them to a relationship by its alias, and unlink by detaching. For content_instances and documents sides you also provide the relevant Template. Attaching and detaching fire relationship.added and relationship.removed events and write logs, so automations can react to links forming or breaking.

Filtering by relationship

Relationships are queryable in Views and Segments: filter records by whether they have or don’t have a given relationship, and by the attributes of the related objects (nested queries).

System vs custom relationships

• System relationships are built into CXF. They’re marked is_system_relationship and can’t be edited or deleted.
• Custom relationships are the user-defined ones described here.

Behaviour & rules

• Valid cardinality only — cardinality_1 and cardinality_2 must each be one or many, forming one of the four types above.
• Aliases must be unique across relationships, and the two sides can’t share an alias.
• content_type is required when a side’s object type is content_instances.
• Pivot fields are rejected on anything other than many_many.
• A scoped side’s template_id must reference an existing Template.
• Because an alias is resolved dynamically, an alias that collides with a built-in method or scope name is shadowed by it — pick distinct aliases.

Seeds

Relationship definitions travel between environments as structural Seeds (they aren’t template instances). Each is a relationships item holding both sides:

[
  {
    "object_type": "relationships",
    "data": {
      "title_1": "Customer",
      "alias_1": "customer",
      "object_type_1": "contacts",
      "cardinality_1": "one",
      "title_2": "Orders",
      "alias_2": "orders",
      "object_type_2": "orders",
      "cardinality_2": "many"
    }
  }
]

Governance & permissions

• Only a super admin or Master can create, edit, and delete custom relationships.
• System relationships (is_system_relationship) can’t be edited or deleted.

API access

Relationship definitions are managed through the API, and dedicated endpoints attach, detach, and update pivot fields on a link. See the API reference.

Related

Object types

The object types a relationship can connect.

Views

Filter records by their relationships.