Every operational problem in HubSpot traces back to a data architecture decision. The duplicate contacts clogging your lists, the broken workflows that silently skip records, the reports that never match finance’s numbers — all of these are symptoms of an architecture that was never properly planned.
This guide is a technical deep-dive into HubSpot’s data model. We cover objects, properties, associations, and pipelines — and explain how each layer influences migration, auditing, and day-to-day CRM operations. Whether you are planning a HubSpot migration, conducting an audit, or building a portal that scales, this is the structural knowledge you need.
The HubSpot Data Model at a Glance
HubSpot's CRM is built on a relational data model with objects at the center. Every piece of information lives on an object as a property, and objects connect to each other through associations.
Think of it as a graph: objects are nodes, associations are edges, and properties are attributes on each node. Here is how the three foundational layers relate to each other:
This graph structure is what makes HubSpot powerful — and dangerous when misunderstood. A contact is not a row in a spreadsheet. It is a node connected to companies, deals, tickets, and custom objects, each with their own properties and relationships. When you change one node, ripple effects propagate through associations to every connected record.
Understanding this graph determines how your data flows through workflows, how reports aggregate information, and what happens when you attempt a migration. There are four foundational layers: standard objects, custom objects, properties, and associations. On top sit pipelines and lifecycle stages, governing how records move through your business processes.
Standard Objects — Contacts, Companies, Deals, Tickets
HubSpot ships with four standard CRM objects, each serving a distinct purpose in the data model.
Contacts
Represent people. Foundation of most workflows, lists, and marketing automation. Primary identifier is email address — HubSpot uses email to deduplicate, updating existing records rather than creating duplicates on import. Also assigned an internal vid and hs_object_id for API operations.
Companies
Represent organizations and serve as the roll-up point for account-level data. Primary matching field is domain. HubSpot uses this for automatic association — a contact with jane@acme.com is automatically associated with the company record that has acme.com as its domain.
Deals
Represent revenue opportunities. Pipeline-based, moving through stages toward closed-won or closed-lost. The pipeline and dealstage properties together drive the majority of revenue reporting. A missing amount or incorrect closedate can distort your entire forecast.
Tickets
Represent support issues, moving through pipeline stages toward resolution. Connect to contacts, companies, and deals, providing a full picture of the customer relationship. Drive metrics like time-to-resolution and volume by category.
| Attribute | Contacts | Companies | Deals | Tickets |
|---|---|---|---|---|
| Primary identifier | Email address | Domain | Deal name | Ticket name |
| Deduplication key | email | domain | None (manual) | None (manual) |
| API object ID | vid / hs_object_id | companyId / hs_object_id | dealId / hs_object_id | hs_ticket_id / hs_object_id |
| Pipeline support | No | No | Yes | Yes |
| Lifecycle stage tracking | Yes | Yes (inherited) | No | No |
| Max custom properties | 1,000 | 1,000 | 1,000 | 1,000 |
| Auto-association | Yes (via email domain) | Yes (via domain) | Manual only | Manual only |
| Marketing automation hub | Primary target | Via association | Via association | Via association |
Each standard object includes system properties that cannot be deleted and, in some cases, cannot be renamed. Contacts have firstname, lastname, email, lifecyclestage, hs_lead_status, createdate, and hs_analytics_source. Companies have domain, name, industry, numberofemployees, and annualrevenue. Deals have dealname, amount, dealstage, closedate, pipeline, and hubspot_owner_id.
Contacts are where most data quality issues surface because they sit at the center of the object graph. For cleanup strategies, see our HubSpot CRM data cleanup guide.
Custom Objects — When and How to Use Them
When standard objects do not fit — subscriptions, locations, projects, product configurations — custom objects let you define new data types with their own properties, associations, and pipelines.
The decision to create a custom object should pass three tests:
- Does this entity need its own properties? Attributes that do not logically belong on an existing object signal a custom object.
- Does this entity need its own associations? If you need to relate this data to contacts, companies, and deals independently, a custom object makes sense.
- Does this entity need its own pipeline? If records move through stages (onboarding, renewal cycles), a custom object with a pipeline is the right structure.
If all three answers are no, a property group on a standard object is simpler and more maintainable. Custom objects are available on Enterprise plans only, and API endpoints differ from standard objects. Third-party integrations may not support them without custom development.
Document purpose, properties, associations, and expected volume before building — undoing a poorly planned custom object is painful. Review with stakeholders first and validate that no existing standard object can serve the same function with property groups.
Properties — The Building Blocks of Every Object
Properties are the atomic unit of HubSpot's data model. Every field on a record, every list filter, every report data point is a property.
System vs Custom Properties
System properties are created by HubSpot — createdate, lastmodifieddate, hs_object_id, and object-specific fields like email or dealstage. They cannot be deleted and many are prefixed with hs_. Custom properties are created by users and admins with no guardrails on creation, which is where most architectural mistakes happen.
Property Types
The type you choose at creation is permanent. You cannot change a text property to a dropdown or a number to a date after creation. To change a type, you must create a new property, migrate data, update all references, and archive the old one.
Single-line & Multi-line
Free-form text fields. Flexible but hard to standardize. Multi-line supports longer notes and descriptions.
Number, Calculated & Score
Numeric values with decimal support, required for calculations. Calculated and score types compute values automatically (Professional+ tiers).
Dropdown, Checkbox & Radio
Predefined options for data standardization. Dropdown select is the most important type for clean, consistent data. Use these wherever possible.
| Property Type | Primary Use Case | Type Changeable? | Calculation Support | List Filter Support |
|---|---|---|---|---|
| Single-line text | Names, short descriptions, identifiers | No | No | Yes (contains, equals) |
| Multi-line text | Notes, long descriptions, comments | No | No | Limited |
| Number | Revenue, counts, scores, quantities | No | Yes | Yes (ranges, comparisons) |
| Calculated | Auto-computed values from other properties | No | Yes (source) | Yes |
| Score | Lead scoring, engagement scoring | No | Yes (source) | Yes |
| Dropdown select | Standardized categorical data | No | No | Yes (is any of, is none of) |
| Multiple checkbox | Multi-select categorical data | No | No | Yes (contains, does not contain) |
| Radio select | Single-choice categorical data | No | No | Yes (is, is not) |
| Date picker | Milestones, deadlines, contract dates | No | Date-based only | Yes (before, after, ranges) |
| Boolean (checkbox) | Yes/no flags, opt-ins, toggles | No | No | Yes (is true/false) |
Date picker / Datetime properties handle milestones and time-based automation. Choose these for any field that represents a point in time — contract dates, renewal dates, last-contacted timestamps.
Property Groups and Naming
Property groups are organizational containers that group related properties in the UI. Create groups that mirror business functions — “Marketing Attribution”, “Sales Qualification”, “Contract Details” — to keep the CRM navigable.
Naming Convention Collapse
A portal with lead_source, Lead Source, leadsource, and lead_src has already lost control. Data fragments across four properties instead of consolidating in one. Reporting becomes unreliable, workflows reference the wrong field, and every import mapping becomes a guessing game.
Establish a naming convention (lowercase with underscores) and enforce it before you scale. Use dropdown selects wherever possible and apply validation rules to prevent garbage data.
For how properties interact with automation, see our guide on HubSpot workflow dependencies.
Associations — How Objects Connect
Associations are the edges in HubSpot's data graph — they define how objects relate to each other and are the most underappreciated layer of the architecture.
Standard Association Types
| Association Type | Cardinality | Primary Supported? | Custom Labels? (Enterprise) | Auto-Created? |
|---|---|---|---|---|
| Contact → Company | Many-to-many | Yes | Yes | Yes (via email domain) |
| Contact → Deal | Many-to-many | No | Yes | Manual only |
| Company → Deal | Many-to-many | Yes | Yes | Manual only |
| Contact → Ticket | Many-to-many | No | Yes | Manual only |
| Company → Ticket | Many-to-many | No | Yes | Manual only |
| Deal → Ticket | Many-to-many | No | Yes | Manual only |
| Standard → Custom Object | Many-to-many | No | Yes | Manual / API only |
| Custom → Custom Object | Many-to-many | No | Yes | Manual / API only |
- Contact to Company: Multiple companies allowed, but one is the primary (drives reporting roll-ups)
- Deal to Contact: Connects revenue opportunities to the people involved
- Deal to Company: Critical for account-level revenue reporting
- Ticket to Contact / Company: Links support issues to requester and organization
Association Labels and Many-to-Many
On Enterprise plans, custom association labels define relationship nature — a contact can be the “Decision Maker” or “Technical Evaluator” on a deal. All HubSpot associations are inherently many-to-many, which enables complex B2B modeling but means orphaned and incorrect associations can proliferate silently.
The Primary Company Problem
Every contact has one primary company association that determines default views and roll-up reporting. When wrong or missing, reporting distorts. This is especially problematic during portal merges where the same contact may be associated with different companies in each portal.
Associations and Automation
Workflow enrollment can reference associated records — enrolling contacts based on their associated company’s properties, or triggering deal workflows from associated contact criteria. This cross-object automation is powerful but fragile.
Orphaned Record Automation Gap
A workflow targeting "associated company industry is Technology" will never reach a contact missing their company association. Orphaned records — contacts without companies, deals without contacts — silently fall through automation gaps, creating invisible data loss in your pipeline.
Pipelines and Lifecycle Stages — Data Flow Mechanics
Deal Pipelines
Each stage has a name, display order, and win probability percentage. You can configure required properties per stage — one of HubSpot’s most underused features, enforcing data quality at the point of action by preventing deals from advancing without critical information.
Ticket Pipelines
Similar to deal pipelines but oriented around support resolution, with stages like “New”, “In Progress”, and “Closed”. They drive metrics like time-to-resolution and volume by category.
Lifecycle Stages
Lifecycle stages represent a contact’s overall relationship with your business. Here is the standard progression:
Subscriber → Lead
Initial engagement. Marketing captures interest through forms, content, and campaigns. Contacts enter the funnel as subscribers and convert to leads through meaningful interaction.
MQL → SQL
Marketing-qualified leads are scored based on engagement criteria and passed to sales. Sales accepts and qualifies them further based on fit and intent, creating the handoff that drives funnel reporting.
Opportunity → Customer
An associated deal is created and moves through pipeline stages. The Opportunity-to-Customer transition typically triggers when the associated deal closes won. This is the critical conversion point for revenue attribution.
Customer → Evangelist
Post-sale engagement, renewal, and advocacy. Customer success workflows maintain the relationship. Evangelists represent your most engaged advocates and are often tracked through NPS scoring or referral activity.
Getting these transitions right is critical for funnel reporting. For what can go wrong, see our post on what you lose in a HubSpot data migration.
Multiple Pipelines
Use separate pipelines when stages fundamentally differ (e.g., “New Business” vs “Renewals”). If stages are the same but routing differs, use a single pipeline with automation. Multiple pipelines affect reporting — cross-pipeline reports require explicit configuration.
How Data Architecture Impacts Migration and Auditing
Migration Challenges
Property mapping is the most time-consuming migration phase. Architectural decisions made months or years earlier determine how painful the process will be.
- Type conflicts — text in source maps to dropdown in destination; values do not match predefined options
- Naming conflicts — both portals have
lead_sourcewith different meanings; merging destroys the distinction - Calculated property loss — calculated and score properties recompute in destination, losing historical values
- Associations exported as flat files lose relational context
- Property types audited and aligned before migration begins
- Naming conventions standardized with prefix mapping documented
- Historical values snapshotted into dedicated text properties before migration
- Associations reconstructed via matching keys with validation passes
Association migration is equally treacherous. Exporting as flat files and reimporting requires reconstructing associations via matching keys (email for contacts, domain for companies). Any mismatch produces orphaned records. For the full process, see our HubSpot-to-HubSpot migration guide.
Audit Implications
Identify Unused Properties
Properties with zero population clutter every interface — forms, list filters, import mappings. They add cognitive overhead and slow down every operational task.
Find Duplicate Properties
Properties that capture the same data under different names fragment information. Data splits across duplicates, making reports incomplete and automation unreliable.
Flag Incorrectly Typed Properties
A date stored as text cannot be filtered by date range. A number stored as text cannot be summed in reports. Wrong types silently break functionality.
Repair Broken Associations
Missing or incorrect associations distort reporting and create automation gaps. Contacts without companies, deals without contacts — each gap is a blind spot in your CRM.
At Jetstack, we evaluate these architectural elements in every portal audit. Understanding the data model is the prerequisite for meaningful remediation.
Best Practices for HubSpot Data Architecture
The most impactful thing you can do for your HubSpot portal is establish and enforce naming conventions before you scale. Every other best practice depends on this foundation.
- Establish naming conventions before you scale. Lowercase, underscored, prefixed by function (e.g.,
mktg_lead_source,sales_qualification_score). Document and enforce. - Use property groups to organize by function. Mirror your teams: “Marketing Attribution”, “Sales Qualification”, “Customer Success”.
- Document custom objects before creating them. Purpose, properties, associations, expected volume — review with stakeholders first.
- Audit associations regularly. Identify contacts without companies, deals without contacts, and companies without any contacts.
- Do not over-create properties. Every property is permanent maintenance overhead in every import mapping, form builder, and list filter.
- Plan pipelines around your actual process. A 12-stage pipeline that reps skip through in three clicks is worse than a 5-stage pipeline that reflects reality.
HubSpot's data architecture is not something you set once and forget. It requires intentional design, regular auditing, and careful management — especially during migrations or portal consolidations. The decisions you make at the object, property, and association level ripple through every workflow, report, and integration in your portal.
If you need help implementing these practices, our implementation services include data architecture planning as a core deliverable.
Frequently Asked Questions
Can I change a property type after creation?
No. Property types are permanent. To change a type, you must create a new property, migrate the data with any necessary transformation, update all workflows, lists, forms, and reports that reference the old property, and then archive it.
How many custom properties can I create?
HubSpot allows up to 1,000 custom properties per object on most plans, with higher limits on Enterprise. The practical limit is lower — portals with hundreds of custom properties per object become difficult to manage. Focus on creating what you actually need.
What happens to associations during a migration?
Associations do not migrate automatically in flat-file imports. You must reconstruct them using matching keys (email for contacts, domain for companies). Unmatched records become orphaned. Complex associations require additional import passes and careful sequencing. See our migration guide for details.
Should I use custom objects or property groups?
Use property groups when data belongs on an existing object without needing independent associations or pipelines. Use custom objects when the data represents a different entity with its own lifecycle and relationships — for example, subscriptions with their own start dates, renewal dates, and statuses.
How do I find unused properties in my portal?
Go to Settings > Properties, select an object, and review the “Records with value” column. Properties with zero population are cleanup candidates. For a thorough approach, export your property list via the API and cross-reference against active workflows, lists, forms, and reports. Our data cleanup guide covers this in detail.
What is the difference between lifecycle stages and deal stages?
Lifecycle stages describe a contact’s overall relationship with your business (Subscriber through Customer). Deal stages describe where a specific revenue opportunity sits in your sales pipeline (Discovery through Closed Won). A contact can be a “Customer” while having a deal in “Proposal” for an upsell. Lifecycle stages are contact-level and business-wide; deal stages are deal-level and pipeline-specific.
HubSpot’s data architecture is not something you set once and forget. It requires intentional design, regular auditing, and careful management — especially during migrations or portal consolidations. The decisions you make at the object, property, and association level ripple through every workflow, report, and integration in your portal.
If you are planning a migration, conducting an audit, or trying to get your data architecture under control, get in touch with us. Jetstack specializes in the architectural work that keeps HubSpot portals clean, scalable, and reliable.