Organizations & Relationships: companies, roles and hierarchy

Overview

The Organizations & Relationships module makes companies first-class entities in the platform. Each organization carries fiscal identity (CPF/CNPJ, EIN, VAT), multiple domains, address, owner and lifecycle stage — and connects everything happening around it: contacts with roles (Financial guardian, Student, Broker…), conversations, CRM deals and a 360 view with aggregated indicators.

The Overview counts only records directly linked to the organization: contacts, conversations, deals, tasks, contracts, orders, charges, subscriptions, meetings and follow-ups. This prevents unrelated data from being mixed in. Parents and branches remain navigable in the Hierarchy tab, each with its own totals.

It is designed for any niche: schools (guardian ⟷ student), accounting firms (accountant ⟷ client), real-estate agencies (guarantor ⟷ tenant), clinics (guardian ⟷ patient), agencies and B2B operations with a parent/branch structure.

Prerequisites

• The module is optional and ships disabled; an administrator must enable it for the account.
• Administration permission to configure relationship types and the module options.
• Contacts already registered so you can link them to organizations (contact import helps here).

Step by step

1. With the module enabled, open Organizations in the sidebar.
2. Click New organization and enter at least the name. Pick the kind (individual or business), the country and the fiscal document — CPF and CNPJ are validated with check digits, and the value stays visible to your team (masked only if an access role says so).
3. Fill in the fiscal registrations (state and municipal) when the company issues invoices — the fields sit right below the document.
4. Add the organization's domains (the first one is primary). With auto-association on, new contacts with a corporate email on that domain are linked automatically.
5. Pick the owner (the agent who owns the account), the size and the timezone — all three are closed lists, so filters and segments match exactly the value you picked here.
6. Fill in the full address: type the postal code and the rest autofills; adjust number and complement. The whole address (street, number, complement, neighborhood, city, state and postal code) shows on the Overview and is the same one company invoices use.
7. In the organization's Contacts tab, link people with a role and title; mark one organization as each contact's primary.
8. In the Relationships tab, connect contacts and organizations using types that carry a label and its inverse (e.g. "Guardian" ⟷ "Dependent"). Apply a niche preset in Settings to start with the right vocabulary.
9. For corporate groups, set the parent on the branch's hierarchy field — the tree shows up in the Hierarchy tab.
10. Use Load demo in Settings to create 10 varied, connected organizations, 20 contacts and native examples of deals, tasks, orders, payments, contracts, meetings, conversations and follow-ups. Removing the demo deletes only those marked records.

Settings & options

• Relationship types: an account-owned catalog with label, inverse and category; idempotent presets for school, accounting, real estate, clinic, agency and B2B.
• Auto-association by domain: toggles linking contacts by corporate email (free domains like gmail.com are ignored; manual links are never overwritten).
• Custom attributes: create organization-specific fields in Settings → Custom Attributes, under the Organizations tab. They appear and are editable in the Custom attributes card on the organization Overview.
• Lifecycle stages: use the stage field (lead, customer…) to filter the list and build segments.
• Import and export: the export writes the address as separate columns (address_zip_code, address_street_name, …), plus registrations and domains — the exact format the import reads. An exported file re-imports without losing fields. The one deliberate exception is the fiscal document: it always leaves masked and the import refuses masked values, so a CPF/CNPJ never travels in the clear inside a spreadsheet.
• Relationships: Add relationship accepts either another organization or a contact; each row opens the corresponding record for further analysis.
• 360 overview: cards summarize every module and preserve navigation to the source record without duplicating information.

Use cases

• School: the organization is the school; parents join as the students' "Financial guardian" and the front desk sees the whole family before replying.
• Accounting firm: every business client is an organization with a validated CNPJ; the accountant follows conversations and charges per company.
• Corporate group: parent and branches in a hierarchy, with the 360 view consolidating each unit's conversations and deals.

Tips, limits & best practices

• The fiscal document stays prefilled in the form after saving, ready to correct. It only shows masked if the access role's tax_id field rule says so.
• The hierarchy rejects cycles (a branch cannot be the parent of its own parent).
• Each contact has one primary organization; the other memberships still count for search and relationships.
• Automations, macros and flows work with organizations: besides Set the contact's organization and Set organization lifecycle stage, there are Set organization field (document, address, email, phone, timezone, registrations…) and Set organization custom attribute. So a flow that collected the tax id or the postal code writes it straight onto the record.
• Conditions and segments now reach email, phone, website, timezone, document scheme and the address components (city, state, neighborhood, street, postal code) — you can finally ask "which companies in SP have no email".
• In messages, campaigns, follow-ups and flows, use the organization variables: {{organization.address}} (full address), {{organization.address_city}}, {{organization.state_registration}} and the rest. Contracts do not have these variables yet: a contract template resolves contact.*, crm_item.*, conversation.*, account.* and company.* (your own issuing company) — use a manual variable for counterparty company data.

Troubleshooting

• I don't see the Organizations menu: the module is disabled for the account — ask an administrator.
• Document rejected: the value failed validation (CPF/CNPJ check digits or EIN/VAT format). Check the number and the selected country.
• Contact was not auto-associated: confirm auto-association is on, the email domain is corporate and the contact didn't already have a manual link.
• Cannot delete a relationship type: it is in use by existing relationships; remove those first.
• Postal code, street, number or state looked empty when editing: this was a bug, now fixed — the form did not read those four keys and, on save, wrote the blanks over what was stored. The form now loads the whole address, and a partial write never clears a field that was not sent. If an address was lost before the fix, just fill it in again.
• I see Tax ID, Postal code, Street, City… among the contact attributes: those are the seven legacy payment fields, now superseded by the contact's native fiscal and address fields. An administrator can retire them with rake "organizations:cleanup_legacy_payment_attributes[<account_id>,apply]" — the task migrates the values to the native fields and removes only the definitions; no data is deleted.

See also

• Contacts: import and segments
• Custom attributes
• CRM: pipelines and deals