All docs

Relations between objects

Link records of one object to records of another, see both sides, and choose what happens when a linked record is deleted.

Updated . 4 min read.

A relation links records of one object to records of another: a project belongs to a company, an invoice belongs to a project, a person works with several properties. You can also relate an object to itself, for example a project with sub-projects.

Create a relation

  1. Open Settings, then Data model, and choose an object.
  2. Under Relations, choose Add relation.
  3. Pick the other object and how they connect:
    • One to many - one of these has many of the other (a company has many projects).
    • Many to one - the other way round.
    • Many to many - either side can have many (people and properties).
  4. Name the field on each side.

A field appears on both objects, so you can see the link from either side. On a record page the linked records are listed in their own panel, with a table of their main details.

Link records

On a record page, choose Link in a relation panel and search for the record. In a table, tick several records and use Link to to link them all at once. Records can be linked when you import them too: put the name of the related record in the column.

Links between contacts, companies, deals and tasks

A contact, company, deal or task already has links of its own, and they appear as fields too, so you can see and change them on the record page and through the API:

  • Companies on a contact and Contacts on a company are the same link. It carries a Primary flag (a contact has one primary company; the first company you link becomes it) and a Role such as "CEO". In the relation panel choose Make primary, or select a role to edit it: Enter saves, Escape cancels.
  • Deals and Linked tasks on a contact or a company list the deals and tasks that name it. Linking a deal or a task there points it at this contact or company; removing the link clears it from the deal or task.

Changing these links works like changing them on the deal, task or company itself: the same rules, plan limits and permissions apply, and you need the right to edit every record you link or unlink. These fields cannot be used to filter, sort, group or total a table, and a CSV import does not fill them.

Through the API, ask for them with include=companies and write them with a list of record ids. A company-contact link can also be written as {"id": "...", "is_primary": true, "role": "CEO"}; the records you leave out of the list lose their link.

Notes, tasks and files

Every object, standard or your own, has three built-in relations: Notes (attached_notes), Tasks (attached_tasks) and Files (attached_files). You do not set them up and you cannot change, hide or delete them; they are listed with the other system fields. They are links like any other, so they work in a table the way a relation does:

  • Filter with is empty and is not empty: "Notes is not empty" is every record someone wrote a note on, "Tasks is empty" every record with nothing to do.
  • Show a total in the footer: how many records have notes, how many have none, and the total number of notes, tasks or files of the records the table shows.
  • The tasks of a record are also listed in its Tasks panel once it has some.

Notes, tasks and files are still written where they were: on the Notes and Tasks tabs of a record, with the notes and tasks endpoints, and the file fields. The links follow them, so nothing about those screens or endpoints changes. A contact's notes include the ones written on the contact's own page. A deleted record keeps its notes, tasks and files, so a restore brings them back; they are removed for good with the record. Through the API the fields show as is_system and is_writable: false, with builtin set to notes, tasks or files; writing a value to one is refused.

What happens when a record is deleted

Each relation has a rule for the "one" side:

  • Unlink (the default) - the linked records stay and simply lose the link.
  • Delete along - the linked records are deleted too, in the background. Only available between your own objects.
  • Block - the record cannot be deleted while others are linked to it. You are told which relation holds it.

The rule applies when you delete a contact, company, deal or task as well.

Delete a relation

Deleting a relation removes both fields and every link, in the background. The records themselves are not touched.