hubspot-data-model
This skill should be used when the user asks to "set up the HubSpot data model", "design HubSpot objects", "structure data in HubSpot", "model contacts companies and deals in HubSpot", "set up HubSpot for B2B SaaS", "design HubSpot associations", "plan HubSpot CRM architecture", "set up objects and associations in HubSpot", "model our CRM data in HubSpot", or any variation of designing the data model, object architecture, and associations in HubSpot CRM for B2B SaaS.
HubSpot Data Model
HubSpot's data model is built on four standard objects (Contacts, Companies, Deals, Tickets) and their associations. Every B2B SaaS CRM build starts here. Get the object structure and associations right and everything downstream (routing, reporting, automation, scoring) works. Get them wrong and you'll spend the next two years working around a broken foundation.
The principle: model HubSpot to match how your business actually works, not how HubSpot's defaults suggest it should. The defaults assume a simple sales motion. B2B SaaS deals have buying committees, multi-product lines, and complex account hierarchies.
The 4 Standard Objects
Contacts
A contact is a person. One record per human. Contacts are the atomic unit of HubSpot.
| Field category | Key properties | Why they matter |
|---|---|---|
| Identity | Email (primary identifier), first name, last name | Dedup and communication |
| Role | Job title, seniority level (custom), department | Persona scoring, routing, messaging |
| Company association | Associated company | Account-level reporting and routing |
| Lifecycle | Lifecycle stage, lead status | Funnel tracking, automation triggers |
| Source | Original source, first conversion, lead source detail (custom) | Attribution |
| Scoring | HubSpot score, ICP fit score (custom), engagement score (custom) | Prioritization, MQL triggering |
| Outbound | Sequence status, last contacted, contact owner | Sales operations |
Contact rules:
- One contact per email address. HubSpot enforces this natively. Never create duplicate contacts with the same email
- Every contact must be associated with a company. Orphan contacts (no company) break account-level reporting, routing, and scoring
- Use email as the primary identifier. Not name (too many duplicates). Not phone (too often missing)
- Lifecycle stage lives on the contact, not the company. A company can have contacts at different lifecycle stages (one is an MQL, another is already a customer contact)
Companies
A company is an organization. One record per business entity. Companies aggregate contacts and deals for account-level visibility.
| Field category | Key properties | Why they matter |
|---|---|---|
| Identity | Company name, company domain (primary identifier) | Dedup and enrichment |
| Firmographics | Industry, employee count, annual revenue, country, city | ICP scoring, segmentation, routing |
| Classification | ICP tier (custom), target account flag (custom), ABM tier (custom) | ABM targeting, prioritization |
| Lifecycle | Company lifecycle stage (custom) | Account-level funnel tracking |
| Ownership | Company owner | Account assignment, routing |
| Enrichment | Tech stack (custom), funding stage (custom), founded year | Signal detection, personalization |
Company rules:
- Use domain as the primary identifier. Company names have variations ("Acme", "Acme Inc", "ACME Corp"). Domains are unique
- Enable automatic company creation from contact email domains. When a contact with @acme.com is created, HubSpot auto-creates or associates the Acme company
- Don't store company-level lifecycle on the default contact lifecycle stage. Create a custom "Company Lifecycle Stage" property on the Company object for account-level tracking. This is separate from individual contact lifecycle stages
- Use the "Target Account" property (checkbox) to flag ABM accounts. This is cleaner than lifecycle-based ABM tracking
Deals
A deal is a revenue opportunity. One record per potential transaction. Deals track the sales process from qualified opportunity to close.
| Field category | Key properties | Why they matter |
|---|---|---|
| Identity | Deal name, deal owner | Tracking, accountability |
| Value | Amount, recurring revenue amount (custom) | Pipeline and forecasting |
| Stage | Deal stage, pipeline | Sales process tracking |
| Timeline | Create date, close date, days in current stage (calculated) | Velocity, forecasting accuracy |
| Associations | Associated contacts (multiple), associated company | Buying committee, account attribution |
| Source | Deal source (custom), original lead source (custom) | Attribution, channel ROI |
| Qualification | MEDDPICC fields (custom) or BANT fields (custom) | Deal qualification tracking |
Deal rules:
- Associate deals with ALL contacts involved, not just the primary contact. A deal associated only with the champion misses the economic buyer, technical evaluator, and influencer. This breaks buying committee reporting
- Associate deals with the company. Seems obvious but is missed in manual deal creation
- One pipeline per sales motion. If you have a "New Business" motion and an "Expansion" motion, create separate pipelines. Don't use one pipeline with a "type" field. Separate pipelines get separate reporting, stages, and automation
- Deal name convention: "[Company] - [Product/Use Case] - [Amount]". Standardize it. "Acme - Platform - $80K" is scannable. "New Deal 47" is not
- Never let deals exist without a close date. A deal with no close date can't be forecasted. Make close date required on deal creation
Tickets (for CS/Support)
Tickets track post-sale support requests. Relevant for CS-driven SaaS teams.
| Field category | Key properties | Why they matter |
|---|---|---|
| Identity | Ticket name, ticket owner, status | Tracking, accountability |
| Priority | Priority level, SLA deadline | Response time management |
| Associations | Associated contact, associated company | Customer context |
| Category | Ticket category (custom), product area (custom) | Pattern detection, product feedback |
Ticket rules:
- Associate every ticket with a contact AND a company. Orphan tickets break customer health reporting
- Use ticket categories to track product feedback patterns. If 30% of tickets are about "integration issues," that's a product signal
- Don't use tickets for sales-process tracking. Tickets are for post-sale. Use deal stages for pre-sale
Associations
Associations are the relationships between objects. They're the connective tissue of the HubSpot data model. HubSpot supports many-to-many associations between all standard objects.
Default associations
| Association | Relationship | Use |
|---|---|---|
| Contact → Company | Many-to-many (one contact can be at multiple companies, one company has many contacts) | Links people to organizations |
| Contact → Deal | Many-to-many (multiple contacts on one deal, one contact on multiple deals) | Tracks buying committee per deal |
| Company → Deal | Many-to-many (but typically one company per deal) | Links deals to accounts |
| Contact → Ticket | Many-to-many | Links support requests to people |
| Company → Ticket | Many-to-many | Links support requests to accounts |
Association labels (Enterprise feature)
Association labels add context to associations. "Jane Kim is associated with Deal X" becomes "Jane Kim is the Champion on Deal X."
Recommended association labels for B2B SaaS:
| Association | Labels | Why |
|---|---|---|
| Contact → Deal | Champion, Economic Buyer, Technical Evaluator, Influencer, End User, Blocker | Tracks buying committee roles per deal |
| Contact → Company | Employee (current), Former Employee, Consultant, Board Member | Distinguishes current from past relationships |
| Company → Company | Parent/Child, Partner, Investor, Competitor | Models corporate hierarchies and relationships |
Association label rules:
- Use association labels to track buying committee roles on deals. This replaces manual tracking in notes or custom fields and makes committee reporting automatic
- Keep label sets small: 5-7 labels max per association type. Too many labels creates decision fatigue for reps
- "Champion" is the most important label. If no contact on the deal is labeled as Champion, flag it as a risk in pipeline review
Custom Objects (Enterprise)
HubSpot Enterprise allows custom objects for data that doesn't fit the standard four.
When to use custom objects
| Scenario | Use custom object? | Alternative |
|---|---|---|
| Tracking product subscriptions per customer | Yes | Custom properties on deals don't handle multiple products cleanly |
| Tracking partner relationships | Maybe | Can use Company-to-Company association with labels instead |
| Tracking product usage data | Yes | Custom properties on contacts don't scale for time-series data |
| Tracking marketing campaigns | No | Use HubSpot's native campaign object |
| Tracking tasks/activities | No | Use HubSpot's native task and activity objects |
| Tracking invoices | Maybe | HubSpot Commerce hub or custom object depending on complexity |
Common custom objects for B2B SaaS
| Custom object | What it tracks | Associates with |
|---|---|---|
| Subscriptions | Active product subscriptions per customer | Company, Contact, Deal |
| Product Lines | Products or modules being sold/evaluated | Deal |
| Signals | Buying signals detected (funding, hiring, tech changes) | Company, Contact |
| Territories | Sales territory definitions | Company, Contact |
Custom object rules:
- Don't create custom objects until you've maxed out what standard objects + custom properties can do. Custom objects add complexity to reporting, automation, and API integrations
- Every custom object must associate with at least one standard object. Orphan custom objects are invisible in most HubSpot workflows and reports
- Custom objects require API or Operations Hub to maintain at scale. If you can't commit to API-based data management, don't create custom objects
Property Architecture
Property naming conventions
| Convention | Rule | Example |
|---|---|---|
| Prefix custom properties | Start with a category prefix | icp_tier, abm_status, outbound_last_touch |
| Use snake_case for internal names | Lowercase with underscores | lead_source_detail not LeadSourceDetail |
| Human-readable labels | Clear, concise labels in the UI | Internal: icp_tier → Label: "ICP Tier" |
| Group related properties | Use HubSpot property groups | Group: "ICP Scoring" contains icp_tier, icp_fit_score, icp_segment |
Essential custom properties for B2B SaaS
On Contact:
| Property | Type | Values | Purpose |
|---|---|---|---|
seniority_level |
Dropdown | IC, Manager, Director, VP, C-Level, Founder | Persona routing and scoring |
icp_fit_score |
Number | 0-100 | Firmographic fit scoring |
engagement_score |
Number | 0-100 | Behavioral engagement scoring |
lead_source_detail |
Dropdown | Organic Search, Paid LinkedIn, Cold Outbound, Referral, Event, etc. | Detailed attribution beyond HubSpot default |
outbound_status |
Dropdown | Not Contacted, In Sequence, Replied, Meeting Booked, Opted Out | Outbound campaign tracking |
persona |
Dropdown | Sales Leader, RevOps, Marketing, Engineering, Founder | ICP persona segmentation |
On Company:
| Property | Type | Values | Purpose |
|---|---|---|---|
icp_tier |
Dropdown | Tier 1, Tier 2, Tier 3, Not ICP | Account prioritization |
target_account |
Checkbox | Yes/No | ABM flagging |
abm_tier |
Dropdown | 1:1, 1:Few, 1:Many, Not in ABM | ABM motion assignment |
funding_stage |
Dropdown | Pre-Seed, Seed, Series A, B, C, D+, Public, Bootstrapped | Firmographic segmentation |
tech_stack |
Multi-checkbox | Salesforce, HubSpot, Outreach, Salesloft, etc. | Stack-based targeting |
company_lifecycle_stage |
Dropdown | Prospect, Target, Engaged, Customer, Churned | Account-level lifecycle |
On Deal:
| Property | Type | Values | Purpose |
|---|---|---|---|
deal_source |
Dropdown | Inbound, Outbound, ABM, Referral, Partner, Expansion | Pipeline source attribution |
champion_identified |
Checkbox | Yes/No | Deal health indicator |
multi_threaded |
Checkbox | Yes/No | Deal risk indicator |
competitor |
Multi-checkbox | List of competitors | Competitive intelligence |
loss_reason |
Dropdown | Price, Timing, Competitor, No Decision, Bad Fit, Internal Build | Win/loss analysis |
Data Model by Company Stage
Seed / Pre-Series A (< 10 employees)
Keep it simple:
- Standard objects only: Contacts, Companies, Deals
- 5-10 custom properties max
- One pipeline ("Sales")
- No custom objects
- No association labels (not available on free/starter anyway)
Series A-B (10-100 employees)
Add structure:
- All standard objects active
- 15-25 custom properties
- 2 pipelines (New Business + Expansion)
- Association labels for buying committee roles on deals
- ICP scoring properties
- Lead source detail properties
Series C+ / Scale (100+ employees)
Full architecture:
- Standard objects + 1-2 custom objects (Subscriptions, Product Lines)
- 25-40 custom properties (with strict naming conventions)
- 3+ pipelines (New Business, Expansion, Partner, Enterprise)
- Full association label sets
- Custom reporting dashboards per team
- API-managed data flows for enrichment and sync
Implementation Checklist
Objects and associations
- [ ] All 4 standard objects configured (Contacts, Companies, Deals, Tickets)
- [ ] Auto-association of contacts to companies enabled (by email domain)
- [ ] Association labels created for Contact → Deal (buying committee roles)
- [ ] Association labels created for Company → Company (parent/child) if needed
- [ ] Deal naming convention documented and enforced
Properties
- [ ] Custom properties created with consistent naming convention
- [ ] Properties organized into property groups
- [ ] Required properties set on object creation forms
- [ ] Dropdown values standardized (no free text for categorical data)
- [ ] Lifecycle stages configured per crm-lifecycle-design skill
Pipelines
- [ ] One pipeline per distinct sales motion
- [ ] Deal stages defined with clear exit criteria per stage
- [ ] Required properties set per deal stage (e.g., close date, amount required at all stages)
- [ ] Win/loss properties configured (loss reason, competitor)
Data hygiene
- [ ] Dedup rules configured (match on email for contacts, domain for companies)
- [ ] Required fields enforced on record creation
- [ ] Import process documented with field mapping template
- [ ] Data quality dashboards built per crm-data-hygiene skill
Anti-Pattern Check
- Contacts not associated with companies. Orphan contacts break account-level reporting, routing, and ABM plays. Enforce the association on creation. Enable auto-association by email domain
- One pipeline for everything. New business, expansion, partner, and enterprise deals all in one pipeline with different stages. This breaks stage conversion reporting and forecasting. Separate pipelines per motion
- Deals associated with one contact only. B2B deals have buying committees. Associate all involved contacts with the deal and label their roles. Single-contact deals miss the committee and break multi-threading reporting
- 50+ custom properties with no naming convention. Properties named "Score", "score2", "New Score", "Lead Score Final" are unmaintainable. Prefix and snake_case everything. Delete unused properties quarterly
- Using free-text fields for categorical data. Industry, lead source, seniority, ICP tier must be dropdowns. Free text creates hundreds of variations of the same value and breaks every filter, report, and workflow
- Company lifecycle stored on the contact lifecycle field. A company can have contacts at different stages. Create a separate "Company Lifecycle Stage" property on the Company object
- Custom objects before maxing out standard objects. Custom objects add complexity to every workflow, report, and integration. Exhaust standard object + custom property options first
- No deal source property. HubSpot's default "original source" tracks how the contact found you, not how the deal was sourced. A deal from outbound prospecting on an inbound contact needs a separate deal source property for accurate pipeline attribution
Want agents that use skill files like this?
We customize skill files for your brand voice and methodology, then run content agents against them.
Book a call