Relationships & Bidirectional Sync

Relationships & Bidirectional Sync

What Are Relationship Fields?

Relationship fields let you link records across entity types and contacts. For example, link a "Project" to a "Company", a "Deal" to a "Contact", or a "Product" to multiple "Orders".

Creating a Relationship Field

Add a field with type Relationship to an entity type. Configure:

• Targets — which types of records this field can link to. Choose from:
  • Contacts — link to contact records
  • Any entity type — link to records of a specific custom entity type (e.g., "Companies", "Projects")
  You can select multiple targets, allowing the field to link to contacts and entity records in the same field.
• Cardinality — controls how many links are allowed on each side:
  • One to One — exactly one link in each direction. Example: an Employee has one Office, and that Office is assigned to one Employee.
  • One to Many — this record links to many targets, but each target links back to only one of this record. Example: a Department has many Employees, but each Employee belongs to one Department.
  • Many to One — this record links to one target, but that target can link back to many of this record. Example: an Employee belongs to one Department, but the Department has many Employees.
  • Many to Many — multiple links in both directions. Example: a Project has many Team Members, and each Team Member works on many Projects.

Bidirectional Relationships

Enable Bidirectional on a relationship field to automatically create an inverse field on the target entity type. When bidirectional is enabled:

1. An inverse relationship field is automatically created on each target entity type, pointing back to the source entity type.
2. The inverse field’s cardinality is automatically inverted (One to Many becomes Many to One, and vice versa; One to One and Many to Many remain the same).
3. The inverse field’s name defaults to the source entity type’s plural name.
4. Changes are synced automatically — when you add or remove a link on one side, the inverse side updates to match. For example, if you link Employee #5 to Department "Engineering", the Engineering department record automatically shows Employee #5 in its inverse field.

How Relationship Values Are Stored

Internally, relationship values use reference strings:

• Links to contacts: contact:123
• Links to entity records: entity_type:5:78 (entity type ID : record ID)

For fields that allow multiple values (One to Many, Many to Many), the values are stored as a JSON array of reference strings. In the UI, these are resolved to display the linked record’s name as a clickable link.

Relationship Selector

When editing a relationship field, a search-as-you-type selector appears. It searches across the target entity types and shows results with the record’s display name and a secondary label (email for contacts, entity type name for records). Results are limited to 50 items per search.

Deleting Relationship Fields

Deleting a bidirectional relationship field also deletes the inverse field on the target entity type. All stored link values on both sides are removed.