1. Connect Your HubSpot Account
Click Install app to connect OrgChart to your HubSpot account.
Important: OrgChart is installed at the HubSpot account level. Once an admin installs the app, the account authorization can be used by the rest of the users in that HubSpot account. Individual users may still need access to the app cards in their HubSpot views.
Install app
2. Login and Choose the HubSpot Account
Use your normal HubSpot login. If you have access to multiple HubSpot accounts, choose the account where OrgChart should be installed.
3. Approve Permissions
Approve the requested HubSpot permissions and click Connect app. OrgChart needs access to deals, companies, and contacts so it can show cards, read associated CRM records, create manual contacts inside OrgChart, and generate organization charts from deal context.
The first user who installs OrgChart for a HubSpot account becomes an OrgChart admin by default. Additional admins can be managed later from OrgChart settings.
4. Add OrgChart Cards to HubSpot Views
After installation, HubSpot admins can add OrgChart cards to Deal, Company, and Contact record pages.
Go to HubSpot Settings > Connected Apps > OrgChart > App cards > Manage locations. Add the cards to the views your team uses.
Users can also add cards from a CRM record by clicking Customize, selecting the record view, and adding OrgChart cards from the App card library.
HubSpot permission required: users need Customize record page layout permissions or Super Admin permissions to add app cards to a record layout.
The available cards are:
- Deal Org Chart: available as a middle tab card and right sidebar card.
- Company OrgCharts: available as a middle tab card and right sidebar card.
- Contact OrgCharts: available as a middle tab card and right sidebar card.
5. Deal Cards
The deal card is the main place to create and work with an org chart. The card shows a preview image of the current organization chart for the deal. Click the preview image or Open editor to open the editor.
If the deal has no associated company, OrgChart cannot create a company-level org chart yet. In that case, the card shows an action to associate a company with the deal first.
If the company has multiple org charts, use the selector on the card to choose which chart should be shown for that deal.
6. Company Cards
The company card lists all org charts associated with that company. Each chart shows:
- The org chart preview image.
- The org chart name.
- The deals associated with that chart.
- An action to open the editor through an associated deal.
Company-level charts are shared across deals for the same company. This means one chart can be reused by multiple deals when the sales team is mapping the same account.
7. Contact Cards
The contact card shows org charts from the contact's associated companies. This helps reps understand where a contact appears in the account map without leaving the contact record.
For each chart, the card shows the company, associated deals, preview image, and an Open editor action when there is an associated deal available.
8. The Org Chart Editor
The editor is where you create, organize, and maintain org charts. It opens in a HubSpot modal from the deal, company, or contact cards.
The editor has two main areas:
- Contact list: shows HubSpot contacts and manual contacts available for the company.
- Chart preview: shows the current reporting structure and buying roles.
8.1 Create or Select an Org Chart
- Create a new org chart from the editor when a company does not have one yet.
- Select an existing org chart when the company has multiple maps.
- Org chart names are limited to 40 characters.
- Changing the name, reporting structure, or buying roles regenerates the preview image used in HubSpot cards.
8.2 Define the Reporting Structure
For each contact, select who they report to. Choose No One (Top Level) for top-level stakeholders and Not in org chart for contacts that should remain in the company contact list but not appear in the current chart.
You can also click Organize and drag one person onto another to create a reporting relationship visually. Click Done when finished.
8.3 Assign Buying Roles
Buying roles identify how each person influences the deal. The default roles are:
- 💰 Economic buyer
- ⭐ Champion
- 🛠️ Technical buyer
- 👤 User
- 🛒 Procurement
- ⛔ Blocker
- 📣 Influencer
- ⚖️ Legal
Admins can customize these buying roles in Settings > General > Buying Roles. Custom roles are account-wide and are used in the editor, preview images, and AI generation.
8.4 Add Manual Contacts
You can add contacts that are relevant to the account map even if they are not HubSpot contacts yet. Manual contacts are stored in OrgChart at the company level, so they are available in other org charts and deals for the same company.
Manual contacts show a trash icon in the contact list and can be deleted from OrgChart. HubSpot contacts show the HubSpot icon and are not deleted from HubSpot by OrgChart.
8.5 Preview Images in HubSpot Cards
OrgChart renders a preview image for each org chart so it can be displayed directly inside HubSpot cards. HubSpot does not allow iframes inside cards, so the editor is opened only when the user clicks the image or button.
Preview images are regenerated when the chart is saved, when reporting relationships change, when buying roles change, when the org chart name changes, and when AI generates or updates a chart.
9. Generate Org Charts with AI
OrgChart can generate a suggested org chart from the deal record, associated contacts, associated company, buying roles, titles, and recent engagements recorded in HubSpot.
Click ✨ Generate AI in the editor. While the process runs, the button shows a generating state. When the chart is created, it is marked with the note ✨ Generated with AI. Check for mistakes. in the editor and preview image.
AI may also identify people mentioned in engagements who are not yet HubSpot contacts. If enabled in settings, OrgChart can create them as manual contacts so they can be included in the chart.
Important: AI-generated org charts are suggestions. Review reporting lines, missing contacts, and buying roles before using the chart in a sales process.
10. OrgChart Home Page
The OrgChart home page lists org charts created in the account. It is useful for admins and managers who want to review account maps without opening each HubSpot deal.
From the home page, users can:
- View paginated org charts.
- Open the editor for a selected chart.
- Download the preview image.
- Delete an org chart.
11. Settings Overview
Only OrgChart admins can manage account settings. Settings are available from the HubSpot app settings page and from OrgChart cards when the user has access.
The main settings areas are:
- General: user access, AI provider, automation, subscription, account deletion, and buying roles.
- Users: user plan and admin management.
12. General Settings
12.1 User Access
- Allow manual contacts: lets users add non-HubSpot contacts to company org charts.
- Allow AI-created contacts: lets AI generation create manual contacts when a person appears in engagement evidence but is not already a contact.
12.2 AI LLM Provider
Admins can enable or disable AI features and choose the AI provider used to generate org charts. The AI workflow uses available deal information, contacts, company context, and engagement records.
If Azure OpenAI is selected, provide the Azure resource name or base URL and API key. API keys are stored encrypted.
12.3 Deal Properties and Engagement Lookback
Admins can control how many days of engagements AI should consider and whether to include all deal properties or only selected deal properties. This is useful when your HubSpot account has many custom properties that are not relevant to account mapping.
12.4 Automations
Automations are enabled by default. Depending on settings, OrgChart can:
- Generate an org chart automatically when a deal is first loaded and no chart exists yet.
- Create org charts for new deals.
- Create org charts when a company is associated with a deal.
12.5 Buying Roles
Buying roles are account-wide. Admins can edit the icon, label, and value for each role, add new roles, remove unused roles, or restore the defaults.
Changing buying roles affects the editor, AI generation, and future preview image generation. Existing contacts that already have a removed role may need to be updated manually.
12.6 Manage Subscription
Free accounts can create up to five free org charts. OrgChart lets free users create a sixth chart, then shows the paywall and requires an upgrade before more charts can be created.
Admins can upgrade to an individual plan or team plan from the card paywall or from Settings. Paid admins can open the Stripe customer portal from Settings to manage billing.
12.7 Delete Account
Deleting an account permanently removes OrgChart data stored by the app, including users, deals, companies, contacts, org charts, preview images, and local billing records. It does not delete your HubSpot account.
Cancel paid subscriptions before deleting the account.
13. User Management
The Users tab lets admins manage OrgChart users for the account.
- Plan: change a user between free, premium, unregistered, or deleted states.
- Admin: make a user an OrgChart admin or remove admin access.
- Remove: remove a non-admin user from the OrgChart account.
Changing a user's plan does not cancel or change the Stripe subscription by itself. Billing must be managed from the customer portal.
14. I Cannot Install the App
You may not have permission to install apps in HubSpot. Ask a HubSpot Super Admin to install OrgChart or grant you permission to install marketplace apps.
15. I Cannot Add Cards to My View
You need Customize record page layout permissions or Super Admin permissions in HubSpot to add cards to record views.
If you can see OrgChart in Connected Apps but cannot add cards, ask a HubSpot admin to add the cards to the shared record layout.
16. The Card Says OrgChart Must Be Reconnected
If the HubSpot token expires, is revoked, or required scopes change, OrgChart will show a reauthorization message on the card. Click the Reconnect action and approve the permissions again.
17. The Editor Does Not Open for a Deal
Org charts are company-based. If a deal has no associated company, OrgChart cannot create or open the editor. Associate a company with the deal first, then refresh the card.
18. The Preview Image Is Not Updating
Preview images are regenerated when changes are saved. If the HubSpot card still shows an older image, close the editor and refresh the card or record. The card appends a refresh token to preview image URLs to avoid stale cached images.
If the issue continues, open the editor, make a small change, and save again to force regeneration.
19. AI Generation Fails
AI generation can fail if AI is disabled in settings, the selected provider is not configured, the deal has no contacts, or HubSpot engagement data cannot be read. The editor shows an error message when generation fails.
Check:
- The account has AI enabled.
- The selected LLM provider is configured.
- The deal has an associated company and contacts.
- The app is still authorized in HubSpot.
20. AI Autofill Is Not Taking Information from My Emails
To enable AI Autofill from email activity, you may need to reauthorize the app so OrgChart can use the newer permissions required to read email engagement data.
Install appIn all cases, the information extracted from emails is limited to the initial portion of each email. This helps avoid processing repetitive long threads, legal disclaimers, and other non-essential content.
If critical deal information is buried deep within email threads or other engagements, AI might not capture or interpret it accurately. AI can also hallucinate, so always check important facts before relying on the generated org chart.
21. Billing or Subscription Issues
Admins can manage billing from Settings > General > Manage Your Subscription. The customer portal opens in a new tab because Stripe blocks the portal inside some embedded contexts.
If the portal cannot find your subscription, contact support with the HubSpot account name and the email used for purchase.
