HubSpot Custom Objects and Properties: A Complete Guide to CRM Data Architecture

HubSpot CRM data architecture is the structural design governing how your customer data is stored, organized, and related within the platform. At its core, the architecture consists of four layers: objects (database tables like Contacts, Companies, Deals), records (individual instances within each object), properties (individual data fields on each record), and associations (relationships connecting records across different objects). This hierarchy determines what’s architecturally possible in HubSpot.

Key Takeaways

• Custom objects unlock many-to-many relationships that standard objects cannot support, enabling complex data models like subscription tracking, asset management, or multi-location account structures.
• Property sprawl degrades system performance: teams routinely create 200+ custom properties when 40 would suffice, creating reporting bottlenecks and user confusion.
• API names are permanent once created: unlike display labels, internal property names cannot be changed after creation, requiring upfront naming conventions.
• Associations are directional and limited: HubSpot enforces association label limits (100 per object pair) and cardinality rules that constrain certain relationship types.

Why This Matters: The Property Sprawl Problem

Most HubSpot portals suffer from uncontrolled property creation. Marketing creates lead_source_campaign, Sales adds campaign_source, and Operations builds utm_campaign_source—three properties tracking identical data. This architectural chaos compounds over time:

The symptoms: Reports break when property names change. Workflows reference deprecated fields. Sales reps see 80+ properties in contact records when only 12 matter. AI tools trained on your data return inconsistent results because there’s no single source of truth.

The mechanism: HubSpot doesn’t enforce property governance by default. Any user with sufficient permissions can create custom properties without validation, naming standards, or cross-functional review. Teams operate in silos, unaware that the property they need already exists under a different name.

The solution requires understanding the foundational architecture—what objects are, how properties function within them, and when custom objects solve problems that properties alone cannot.

Understanding the Hierarchy: Objects → Records → Properties → Associations

Objects are database tables. Records are rows. Properties are columns. Associations are foreign keys connecting tables. If you understand relational database design, you understand HubSpot’s CRM architecture—the terminology differs but the concepts are identical.

Objects: Standard vs. Custom

Standard objects are HubSpot’s pre-built database tables. Every portal includes Contacts, Companies, Deals, and Tickets by default. Depending on your subscription tier, you also get Leads, Line Items, Quotes, Products, and several others. Standard objects ship with pre-configured properties (email, firstname, lifecyclestage) and native feature support (email tracking, lifecycle automation, pipeline reporting).

Custom objects are user-defined tables for data that doesn’t fit standard buckets. We frequently observe teams creating custom objects for Subscriptions (linking Contacts to recurring products with renewal dates), Assets (tracking equipment associated with Deals), Locations (managing multi-location companies), or Projects (connecting Services to Deals with project-specific timelines).

Custom objects behave identically to standard objects—they support custom properties, associations, workflows, and reporting. The difference is that you define the entire schema.

When to Use Custom Objects vs. Adding Properties

This decision determines how much complexity you’re signing up for. Create a custom object when:

1. One-to-Many Relationships Exist Where the “Many” Side Needs Independent Tracking

Example: A manufacturing company where each Company has multiple Facilities, and each Facility has its own address, contact, and order history. Adding facility_1_address, facility_2_address properties to Company records creates schema fragility—what happens at Facility #4?

Solution: Create a “Facilities” custom object. Each Facility record associates to one Company (many-to-one) with properties for facility_address, facility_contact, facility_type. Deals and Tickets associate to specific Facilities rather than just Companies.

2. You Need Many-to-Many Relationships

Example: Deals involving multiple Contacts from different Companies (partner deals), where associating Contacts directly to Deals loses context about which Company each Contact represents.

Solution: Create a “Deal Participants” custom object positioned between Contacts, Companies, and Deals. Each Deal Participant record associates to one Contact, one Company, and one Deal, with properties like participant_role and company_relationship.

3. The Data Has Its Own Lifecycle Independent of Standard Objects

Example: Annual service contracts that renew independently of the original Deal. The contract has its own renewal date, value, terms, and lifecycle (active, expiring, renewed, cancelled).

Solution: Create a “Contracts” custom object associating to Deals (one-to-one initially) and Companies (many-to-one). Workflows trigger 90 days before contract_end_date to initiate renewal processes. Reporting separates new business revenue (Deals) from renewal revenue (Contracts).

Add Custom Properties (Not Objects) When:

1. The data describes attributes of an existing record. Example: Industry-specific fields like compliance_status on Company records.

2. You’re tracking simple yes/no, date, or category information. Example: attended_trade_show_2024 checkbox on Contact records.

3. The relationship is strictly one-to-one. Example: Each Deal has one primary_competitor text field.

The architectural cost of custom objects is association complexity. Every custom object requires defining association labels, cardinality rules, and cross-object workflow logic. Teams routinely underestimate this maintenance burden.

Records: The Individual Instances

Records are rows in your database tables. Each record has a unique HubSpot ID (visible in the URL: https://app.hubspot.com/contacts/PORTAL_ID/contact/RECORD_ID), a creation timestamp, and values for properties defined on that object.

Records carry history. HubSpot logs every property change, association modification, and activity (emails sent, meetings scheduled, deals created) on the record’s timeline. This history enables audit trails but increases data storage, particularly for high-activity records like support tickets.

Properties: The Individual Data Points

Properties are fields on records. Each property has an internal API name (permanent, cannot be changed), a display label (editable, what users see), a field type (text, number, date, dropdown, boolean), optional default values, and field constraints (required, unique, validation patterns).

Property Types and Common Use Cases

Text fields store up to 65,536 characters. Multi-line text fields do not support workflows that evaluate specific values—use dropdown selects for workflow branching logic.

Number properties support decimals but use floating-point precision, creating rounding errors in financial calculations. For currency values requiring exact precision (payment amounts, invoice totals), store integer values in cents, then divide by 100 in reporting.

Date properties store dates only (no time component) unless you use date picker properties, which include time. Workflow triggers evaluate dates in the portal’s timezone setting, creating edge cases when users operate across timezones.

Dropdown select properties define fixed options at the property level. Each option has an internal value (permanent) and a display label (editable). Workflows reference the internal value, so renaming “Qualified Lead” to “SQL” doesn’t break workflows, but changing the internal value from qualified_lead to sql does.

Calculated properties use HubSpot formulas to derive values from other properties. Formulas recalculate automatically when source properties change, but calculation errors fail silently—the property remains blank rather than displaying an error. Teams building complex calculated properties test extensively because debugging requires deconstructing formulas manually.

Property Availability by Object Type

Property availability varies by object. Contacts have email (unique identifier), firstname, lastname, lifecyclestage. Companies have name, domain (unique identifier for automatic company creation), industry, annual_revenue. Deals have dealname, amount, closedate, pipeline. Lifecycle stage exists on Contacts and Companies but not Deals (Deals have deal stage instead). Owner properties exist on all standard objects.

Cross-object reporting requires associations. You cannot build a Contact report grouped by the Contact’s associated Company’s industry property without ensuring every Contact associates to a Company. Missing associations create data gaps invisible until you filter by cross-object properties.

Editing Properties in HubSpot

Navigate to Settings → Data Management → Properties to view all properties. Search by name or filter by object type. Clicking a property reveals its configuration: display label, internal name, description, property type, field settings (dropdown options, number formatting), rules (required, unique, validation), and usage (which forms, workflows, reports reference it—critical before deprecating).

Key limitation: Internal API names are permanent. If you create lead_source_campaign and later realize it should be utm_campaign_source, you cannot rename it. You must create a new property, migrate data, update workflows and reports, then deprecate the old property.

Standard approach: Establish property naming conventions before building. Use prefixes like hs_ (HubSpot default), custom_, or domain-specific prefixes (mfg_ for manufacturing, pe_ for private equity) to signal property provenance and purpose.

Associations: How Objects Connect

Associations map relationships between records. The association Contact → Company indicates a contact person works at a specific company. Associations are directional—you associate a Contact to a Company, creating a relationship visible from both records.

Association Types and Cardinality

HubSpot enforces different cardinality rules depending on the object pair:

• Contact → Company: Many-to-one (each Contact associates to one primary Company, but Companies have many Contacts)
• Contact → Deal: Many-to-many (Contacts associate to many Deals, Deals have many Contacts)
• Deal → Company: Many-to-one (each Deal belongs to one primary Company)
• Ticket → Contact: Many-to-one (each Ticket has one primary Contact)

Custom objects support fully customizable association cardinality defined during object creation.

Association Labels

Association labels clarify how two records relate. Standard Contact → Company associations have the default label “Contact at company.” Custom labels support use cases like Deal → Contact labels (“Decision Maker,” “Influencer,” “End User”) clarifying each Contact’s role, or Ticket → Contact labels (“Ticket Creator,” “CC’d on Ticket,” “Account Manager”) distinguishing who opened the ticket versus who monitors it.

The architectural complexity: Association labels require maintenance. Teams create decision_maker_2024, primary_decision_maker, and dm labels—all representing identical concepts. This proliferation creates reporting challenges identical to property sprawl.

Viewing Associations in HubSpot Data Model Overview

Navigate to Settings → Data Management → Data Model to visualize all objects and associations. This view displays all standard and custom objects as nodes, association lines connecting objects, association label counts per object pair, and property counts per object. Portals with 15+ custom objects and 50+ association labels typically struggle with user adoption (too complex for reps) and reporting performance (cross-object queries slow down).

Technical Limitations You Need to Know

Understanding these constraints prevents building architectures HubSpot cannot support:

Record and Object Limits

• Custom object records: 150,000 per object (Professional), 2 million per object (Enterprise)
• Total custom object records: 600,000 across all objects (Professional), unlimited (Enterprise)
• Marketing contacts: 100,000 (Marketing Hub Professional baseline)
• Custom objects allowed: 10 (Professional), 100 (Enterprise)

Property Constraints

• Custom properties per object: 10,000 maximum (Enterprise tier)
• API names are permanent: Cannot be changed after creation
• Text field display performance: Degrades above 1,000 characters in record views
• Multi-line text in workflows: Cannot evaluate specific values for branching logic
• Calculated property failures: Fail silently (property remains blank, no error message)

Association Limits

• Association labels per object pair: 100 maximum
• Association label deletion: Cannot delete if any records use them (only archive)
• API call consumption: Associations consume API limits when syncing via integrations

Field-Specific Constraints

• Number property precision: Floating-point precision creates rounding errors in financial calculations
• Date property timezones: Workflows evaluate dates in portal timezone, not user timezone
• Calculated property dependencies: Chains of calculated properties (C depends on B depends on A) introduce calculation lag; limit to 2 levels maximum

Workflow Limitations

• Custom object workflow re-enrollment: Limited compared to contact/company workflows
• Cross-object workflow triggers: Complex workflows spanning multiple objects slow execution

When to Use Custom Objects: Architectural Scenarios

Scenario 1: Many-to-Many Relationships Requiring Context

Problem: A SaaS company sells to enterprises where each Deal involves multiple Contacts from multiple Companies (multi-party deals). Standard associations lose context—you cannot record which Company each Contact represents or their role relative to their Company.

Solution: Create a “Deal Participants” custom object positioned between Contacts, Companies, and Deals. Each Deal Participant associates to one Contact, one Company, one Deal, with properties like participant_role (Decision Maker, Influencer) and company_relationship (Buyer, Implementation Partner).

Outcome: Reporting answers “How many deals involved partner companies?” and “What percentage of Decision Makers came from external consultancies?” because relationship context is stored as data.

Scenario 2: Tracking Multiple Instances of the Same Entity

Problem: A manufacturing company manages multi-location customers where each Company has 3–10 physical facilities. Each facility needs its own address, primary contact, order history. Adding facility_1_address, facility_2_address properties creates rigid schema that breaks when facilities exceed predefined limits.

Solution: Create a “Facilities” custom object. Each Facility associates to one Company (many-to-one) with properties for facility_address, facility_contact, facility_type. Deals and Tickets associate to specific Facilities rather than just Companies.

Outcome: Sales reps see all facilities for a Company in one place. Service tickets route to facility-specific contacts automatically. Reporting aggregates revenue by facility type without manual tagging.

Scenario 3: Independent Lifecycle Tracking

Problem: A professional services firm sells annual contracts that renew independently of the original Deal. The contract has its own renewal date, value, terms, lifecycle (active, expiring, renewed, cancelled). Storing this as properties on the Deal record conflates initial sale with ongoing contract management.

Solution: Create a “Contracts” custom object. Each Contract associates to the originating Deal (one-to-one initially) and to the Company (many-to-one). Properties include contract_start_date, contract_end_date, contract_value, auto_renewal_enabled. Workflows trigger 90 days before contract_end_date for renewal processes.

Outcome: Reporting separates new business revenue (Deals) from renewal revenue (Contracts). Ops builds workflows creating renewal Deals automatically from expiring Contracts. Sales forecasts include both new opportunities and scheduled renewals.

When NOT to Use Custom Objects

1. The Data Fits Existing Objects with Additional Properties

Creating a custom “Leads” object when HubSpot’s native Leads object (Sales Hub Pro+) exists introduces unnecessary complexity. Adding 5–10 custom properties to the standard Leads object handles most qualification workflows without architectural overhead.

2. You’re Avoiding Property Limits

HubSpot allows 10,000 custom properties per object (Enterprise). Teams occasionally propose custom objects to “organize properties into separate tables.” This misunderstands database design—properties and objects serve different architectural purposes. If you need better property organization, use property groups (Settings → Properties → Groups) to categorize properties within objects.

3. The Relationship is One-to-One Without Complex Attributes

If every Deal has exactly one “Project Plan” and the project plan contains 10 attributes (start date, project manager, estimated hours), storing these as properties on the Deal object is simpler than creating a “Project Plans” custom object with one-to-one associations. Custom objects add value when relationships are complex (one-to-many, many-to-many) or when the related entity has independent lifecycle.

Common Implementation Pitfalls

Pitfall 1: Ignoring API Name Permanence

Teams name properties descriptively in the moment: q4_2024_campaign_source. Six months later, this property tracks campaigns across all quarters, but the API name q4_2024_campaign_source is permanent. Workflows and API integrations reference the outdated name indefinitely. Use generic, timeless API names (campaign_source_primary) even if initial use cases are time-bound.

Pitfall 2: Creating Associations Before Defining Labels

Default association labels (“Contact at company,” “Company to deal”) lack specificity. Once records associate without custom labels, retroactively applying labels requires manual editing or API-based bulk updates. Define association labels during custom object creation, before associating any records.

Pitfall 3: Over-Indexing on Custom Objects for “Organization”

Custom objects are not folders for organizing properties. Teams sometimes propose a “Company Details” custom object to hold company attributes, with one-to-one associations to Company records. This doubles record counts, complicates reporting (now requiring cross-object queries for basic company data), and provides no architectural benefit. Use property groups and record customization (hiding irrelevant properties from specific user roles) rather than artificial object segmentation.

FAQ

Next Steps: Validate Before You Build

Architectural mistakes in CRM data models are expensive to fix retroactively. Before creating custom objects or adding 50+ custom properties:

1. Audit existing properties for duplicates and deprecated fields. We frequently observe 30–40% property reduction after deduplication.

2. Document your intended data model on paper or in a spreadsheet. Map objects, associations, and cardinality rules visually before building in HubSpot.

3. Test with a small data set (10–20 records per object) to validate reporting and workflow behavior before full rollout.

If your portal already has 10+ custom objects and 300+ custom properties, a HubSpot Portal Audit identifies architectural debt, property sprawl, and association complexity slowing your team’s performance. We document what exists, highlight what’s deprecated, and map a remediation roadmap aligning your CRM architecture with your actual operational needs—not what was built in 2019 and never revisited.