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

### From a conversation or contact

1. Open the contact panel in the conversation, or open the contact details, and expand **Organizations**.
2. Select **Link an organization**, search by name and choose an existing organization. Organizations already linked to this contact are not offered again.
3. If the organization does not exist, select **Create organization**. Complete the native organization form, including any fiscal, address, domain or logo details you need, and save. Creating requires administrator or organization management permission; standard agents can link existing organizations.
4. After saving, the new organization is selected in the link form. Enter the contact's role (optional), choose **Set as primary** when appropriate and select **Link**. Creating a record does not link it automatically.
5. If creation fails, correct the details in the open form and retry. If linking fails after creation, keep the selected organization and retry the link: the organization remains registered and does not need to be created again. If the change was saved but the list could not be refreshed, use **Retry loading**; this reloads the links without repeating the write.
6. Cancel closes the form without linking. Reopen it to select the registered organization. A page reload reads the persisted links; switching to another contact keeps that contact's organizations separate.

The search, selection and actions support keyboard navigation. The primary option announces whether it is selected. Loading, an empty list, no search results and errors have separate messages.

## 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](/hc/ajuda/articles/contacts-crm-contatos-import-segmentos-en)
- [Custom attributes](/hc/ajuda/articles/contacts-crm-atributos-personalizados-en)
- [CRM: pipelines and deals](/hc/ajuda/articles/contacts-crm-crm-pipelines-kanban-negocios-en)