Updated 8 October 2026. This guide covers the current HubSpot editor and AI-assisted chart generation.
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, maintain people added in OrgChart, and generate charts from company and 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 shows a preview of the chart selected for that deal. Click the preview or Open editor to work on it. You can create and generate charts from either a deal or its associated company; both use the same company-based generation workflow.
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 directly, even when no deal is associated.
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 the chart is available to the user.
8. The Org Chart Editor
The editor is where you create, review, and maintain org charts. It opens from the deal, company, or contact cards. The same chart can be reused across deals for one company.
The editor has two main areas:
- Chart: shows people, reporting lines, and any useful unfilled roles. Optional relevance and engagement switches add visual cues to the boxes.
- Contact list: shows HubSpot contacts and people added in OrgChart, including those not yet placed on this chart. Use it to select a manager, assign buying roles, or return a person to the chart.
HubSpot contact names open the related HubSpot contact record in a new browser tab. Manual contacts stay inside OrgChart and do not link to HubSpot until they are created as HubSpot contacts.
Click a box to open its details panel. It shows the person's title and contact information, the current relationship, its confidence and available sources, and actions to confirm or change the placement. An Enriched marker means some displayed details came from a public or third-party source; hover over it to see the source type. Enriched details are not, by themselves, proof of a reporting line.
The main editor controls are:
- Generate with AI / Update with AI: creates or refreshes a suggested chart using the workflow explained in section 9.
- Unsaved / Saving / Saved: shows the save state. Relationship and placement edits save automatically; you can also click the button to save or retry a failed save. Wait for Saved before closing the editor.
- New / Delete: creates another chart or deletes the selected chart, subject to account permissions.
- Edit / Done: enables or ends layout editing. You can also drag a person onto another person to change their manager.
- Full screen: opens the editor in a larger browser tab when the embedded HubSpot modal is too small.
- Download: downloads the current org chart image. If relevance or engagement switches are enabled, the downloaded image uses those same visual cues.
- Zoom and fit: adjust the visible chart. Undo and Redo step through recent editor changes.
Tip: hover over the upper edge of a person's box or its incoming line to confirm the relationship with the check mark, or choose the change-manager icon. After choosing a new manager, click the destination box. Hover over the lower edge of a box and click + to add a direct report. The details panel offers the same actions.
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 person, choose a manager in the contact list or use the actions on the chart. No manager recorded (top level) leaves the person at the top of the chart; Not in org chart keeps them available in the contact list without displaying them on this chart. For an AI-suggested line, Confirm records that a user reviewed it.
The line styles distinguish Confirmed, Likely, Tentative, and Grouped. Grouped means the person belongs in that branch but the direct manager is not established. It should not be read as a verified reporting line. Select a box to inspect the explanation, evidence confidence, and source links when available.
Use Remove from chart to unplace a person without deleting them. If other people sit below that person, OrgChart keeps the branch together under an unfilled manager role until you choose a replacement. Empty placeholders can be removed; a branch with people below it can be removed as a branch after confirmation. These actions do not delete HubSpot contacts.
8.3 Assign Buying Roles
Buying roles identify how each person influences the deal. OrgChart uses HubSpot's native Buying role contact property as the source of truth. The default HubSpot buying-role options are:
- ⛔ Blocker
- 💰 Budget Holder
- ⭐ Champion
- ✅ Decision Maker
- 👤 End User
- 🤝 Executive Sponsor
- 📣 Influencer
- ⚖️ Legal & Compliance
- ● Other
When you assign a buying role in OrgChart, OrgChart updates the HubSpot contact's Buying role value. This keeps HubSpot and OrgChart coordinated instead of maintaining a separate app-only role list.
To add, rename, remove, or reorder buying roles, update the Buying role contact property options in HubSpot. Admins can use Settings > General > Buying Roles > Manage buying roles in HubSpot to open the HubSpot property settings page. After a new role is added in HubSpot, it normally appears in OrgChart after the short property cache refresh, usually within about five minutes.
OrgChart settings are only for changing the icons shown next to each HubSpot buying role. The role names and internal values come from HubSpot and should be managed there.
8.4 Review Contact Intelligence
OrgChart calculates deterministic contact intelligence scores for each contact in the company org chart. The scores are designed to help the team quickly scan who looks commercially relevant and who has recent engagement, without changing HubSpot data.
The contact list shows compact Rel and Eng badges. The contact sidebar shows Total, Rel, Eng, and associated deal badges in one row. Click the Intelligence title in the sidebar to expand the explanation, including the main reasons and source facts used for the score.
The org chart boxes do not show intelligence badges by default. Use the Relevance switch to show relevance badges, background tint, and a small size cue. Use the Engagement switch to show engagement badges, border strength, border color, and shadow. Low engagement has no shadow so stale or unknown contacts do not look visually over-emphasized.
Total score: round((relevanceScore * 0.6) + (engagementScore * 0.4)). Scores are grouped as High from 75 to 100, Medium from 45 to 74, and Low from 0 to 44.
Relevance score: starts from a neutral baseline and increases or decreases from account-map signals. Strong buying roles such as decision maker, executive sponsor, budget holder, and champion add the most weight. Influencer, end user, legal and compliance, and custom roles add smaller weight. Blocker reduces the score unless other strong deal signals are present. Associated deal count and open deal amount add points relative to the other contacts in the same company org chart, so the score is company-relative. Lifecycle stage, lead status, and title signals such as C-level, VP, Head, Director, Procurement, Legal, Finance, Security, and IT add limited extra context.
Engagement score: also starts from a neutral baseline. Recent HubSpot engagement is the strongest signal: activity within 7 days is high, 8 to 30 days is medium, 31 to 90 days is weak, and older activity is stale. Sales activity count and contacted count add capped points so noisy contacts do not dominate the score. Email replies add more weight than email clicks or opens. If HubSpot has no recent activity date and no activity counts, OrgChart shows No recent engagement data instead of treating the contact as a proven zero-engagement stakeholder.
OrgChart reads available HubSpot contact properties such as last contacted, last activity, last engagement, number of sales activities, number of times contacted, email open/click/reply dates, buying role, associated deal count, recent deal amount, and total revenue. If a HubSpot portal does not expose one of those properties, OrgChart retries safely without it and calculates the score from the remaining available signals.
8.5 Add Manual Contacts
You can add people who are relevant to the account map even if they are not HubSpot contacts yet. A company-level manual person can be reused across charts and deals for that company. You can also create a person in the chart editor and, when appropriate, add that person to HubSpot.
Manually added people can be deleted from OrgChart where the delete action is offered; this does not delete a HubSpot contact. Use Remove from chart instead when you only want to unplace someone. Unfilled roles that have been filled or removed are hidden from the active contact and manager choices so they do not keep appearing as duplicates.
Unfilled roles: when the chart has a meaningful missing manager or leader, it may show a lightly shaded role box instead of inventing a person's name. Select it and choose Fill this role to pick an available person or create one. Filling a role is a manual decision, so its new person-to-person reporting line is marked confirmed. Remove an empty role if it is not useful.
8.6 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
Click ✨ Generate with AI for a new chart, or ✨ Update with AI for an existing one. You can start from a company record or a deal with an associated company. Both routes use the same company-based generation workflow; a deal also supplies relevant deal context and links the chart to that deal.
9.1 How a Chart Is Built
- Understand the account: OrgChart gathers the company's identity and available HubSpot contacts, titles, buying roles, and permitted deal and engagement context. It also checks for duplicates and for people whose company affiliation is uncertain.
- Find useful context: when appropriate, it checks public company information and available enrichment sources for leadership, roles, locations, and organizational clues. Public information is especially useful for larger companies; a small team or department chart may rely much more on CRM evidence. Outside information can be missing, old, or mismatched, so it is assessed rather than accepted automatically.
- Build a people-first structure: where credible public leaders and relationships exist, they form the top-level backbone. OrgChart then places CRM people into the most plausible function, region, and seniority level using all available evidence. For smaller or focused charts, it builds around the people and scope actually present rather than forcing a whole-company CEO hierarchy.
- Handle gaps and uncertainty: confirmed relationships remain distinct from likely or tentative ones. If the appropriate manager is unknown, OrgChart can group someone under a branch or show an unfilled role with people below it. It does not need to invent a named manager or make every contact a direct report of the CEO. Contacts with too little reliable context may remain available but unplaced.
- Review and refine: the chart appears with line styles, available sources, and quality indicators. You can confirm a line, choose another manager, fill a role, or add a direct report. Manual corrections are carried forward when you update the chart with AI.
While generation runs, the editor shows an approximate sequence of progress messages. Research and reconciliation can take longer for complex companies; the messages describe the stage of work, not a guaranteed completion time. Depending on account settings, AI can also add a real person found in engagement evidence as a manual contact.
9.2 Read the Result
Chart quality is an overall score that combines evidence confidence, contact coverage, structural plausibility, contact role information, and leadership placement. It is a guide to how usable the chart is, not a guarantee that every reporting line is correct. Open the quality details to see the component scores and explanations. Evidence confidence is shown separately because a plausible hierarchy may still contain inferred relationships.
The relationship details panel shows whether a particular line is confirmed, likely, or tentative, with its explanation and source links where available. A confirmed line may come from an explicit source or from a user's manual review; check the details when that distinction matters. Grouped indicates branch placement, not a known direct manager. If sources disagree, OrgChart may keep a relationship tentative or leave a person unplaced rather than present a conflict as fact.
Important: AI-generated charts are best-effort starting points. Review important reporting lines, current titles, affiliations, missing contacts, and buying roles before relying on the chart in a sales process. For a small or department-only chart, do not assume it represents the entire company.
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 usage, automation, subscription, account deletion, and buying-role icons.
- Users: user plan and admin management.
12. General Settings
12.1 User Access
- Allow non-admin users to delete org charts: lets non-admin users permanently delete org charts. When disabled, only OrgChart admins can delete charts.
- Allow non-admin users to manage manual contacts: lets non-admin users add and delete manual contacts in company org charts. When disabled, only OrgChart admins can manage manual contacts.
- Allow AI-created contacts: lets AI generation create manual contacts when a real person appears in engagement evidence but is not already a HubSpot contact.
12.2 AI Usage
Admins can enable or disable AI features and configure the available AI provider. Generation uses the company and CRM context described in section 9, with public information and enrichment where available and appropriate. Availability of outside sources depends on the service configuration and the company being researched.
If Azure OpenAI is selected, provide the Azure resource name or base URL and API key. API keys are stored encrypted. If AI usage is disabled, AI generation and AI automation are not available to users.
12.3 Deal Properties and Engagement Lookback
Inside AI Usage, admins can control how many days of engagements AI should consider. They can also choose whether AI sees all available deal properties or only selected deal properties. This is useful when a 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:
- Allow AI org-chart automation globally for the account.
- Create org charts for new deals.
- Create org charts when a company is associated with a deal.
The main automation switch must be enabled for the new-deal and company-association automation switches to have an effect.
12.5 Buying Roles
Buying roles are account-wide because they come from HubSpot's Buying role contact property. OrgChart settings show the HubSpot buying-role names and let admins choose the icon OrgChart displays for each one.
Use Manage buying roles in HubSpot to add a new role or change the role options themselves. Use Save icons to save OrgChart icon changes, or Restore default icons to return to the default icon mapping. Changing icons affects the editor, AI generation display, and future preview image generation; it does not rename or create HubSpot buying-role options.
12.6 Manage Subscription
Free accounts can create up to 10 free org charts. OrgChart warns admins as the account approaches the free limit and requires an upgrade before an 11th chart 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, the configured service is unavailable, the HubSpot connection needs attention, or there is too little reliable company information to build a chart. A company with no CRM contacts may still be eligible if verifiable public leaders are found; an empty company record does not guarantee a chart can be generated. The editor shows an error when generation fails.
Check:
- The account has AI enabled.
- The AI service is configured and available.
- The company name or domain is correct and the company has useful CRM contacts or verifiable public information. A deal must be associated with a company.
- 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.
