## 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](/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)