Your HubSpot is cluttered with spreadsheets, excessive custom fields, and disconnected data. Tracking a single customer relationship requires juggling multiple tools and systems. That eventually will be a nightmare, but there's a better way.
HubSpot Custom Objects let you organize your business data properly. They're building blocks that allow you to model your CRM around your actual business instead of forcing your data into rigid categories.
Here's what Custom Objects are, why they matter, and how to use them effectively.
What Are HubSpot Custom Objects?
HubSpot Custom Objects are user-defined data categories that work exactly like standard HubSpot objects (Contacts, Companies, Deals, and Tickets). They let you create specialized records for business items unique to your operations.
HubSpot provides standard objects for people (Contacts), companies (Companies), deals (Deals), and support requests (Tickets). These work well for basic CRM needs.
But when your business needs to track unique items, standard objects fall short. Examples include:
- Physical equipment with serial numbers and maintenance schedules
- Training courses with completion dates and certifications
- Property listings with viewing histories and multiple buyers
- Subscription tiers with renewal dates and usage limits
- Medical equipment across multiple locations
How Custom Objects Function
Custom Objects have full functionality within HubSpot:
- Behave identically to standard objects — No limitations
- Support custom properties — Add any fields needed to store your data
- Allow associations with other records — Connect to Contacts, Companies, Deals, Tickets
- Integrate with reporting — Build dashboards and track metrics
- Work with automation — Trigger workflows, send emails, update records
You model your CRM around your business processes instead of forcing your data into predefined categories.
Why Do HubSpot Custom Objects Exist?
Custom Objects were created in August 2020 to solve tracking one-to-many relationships in CRM data.
Here's a practical example: You run a car dealership and need to track every vehicle in inventory. Each vehicle has a VIN, make, model, mileage, service history, and location. You manage hundreds of vehicles that are constantly moving through sales, service, and inventory.
Before Custom Objects, you had two problematic options:
Option 1: Property Overload
You create custom properties on the Company record:
- Vehicle 1 VIN, Vehicle 1 Make, Vehicle 1 Model
- Vehicle 2 VIN, Vehicle 2 Make, Vehicle 2 Model
- Vehicle 3 VIN…
By vehicle 20, your Company record becomes unmanageable. Reporting is impossible, and you need to create more properties for each additional vehicle.
Option 2: External Management
You keep vehicle data in a separate system—a specialized database or spreadsheet. Now your data exists in two places. Sales teams use HubSpot, and inventory teams use Excel. Nobody has the complete picture, reporting requires manual work, and automation is impossible.
What Problems Do Custom Objects Solve?
Custom Objects eliminate both problems:
- Eliminate data clutter Create one specialized object type instead of dozens of redundant properties.
- Centralize separated data Bring operational data from spreadsheets directly into HubSpot for a single source of truth.
- Enable one-to-many relationships One customer can have unlimited associated instances—vehicles, subscriptions, courses, and equipment.
Using the car dealership example: Create a "Vehicle" Custom Object where each vehicle gets its own record with properties (VIN, make, model, service history, location). Associate vehicle records with the relevant Company or Contact.
Your sales team sees which vehicles each customer owns. Service teams access maintenance history instantly. Reports show real-time inventory across locations. Adding vehicle 500 requires just creating a new record—no database restructuring.
Custom Objects vs. Custom Properties: What's the Difference?
Custom Property = 1:1 relationship. Custom Object = 1:Many relationship
When to Use a Custom Property
Use a custom property when storing a single value about a record.
Examples:
- "What's this contact's job title?" — One contact, one title
- "What's this company's annual revenue?" — One company, one revenue number
- "What industry does this company operate in?" — One company, one industry
Use custom properties for descriptive attributes that have one answer per record.
When to Use a Custom Object
Use a Custom Object when tracking multiple instances of something.
Examples:
- "What are all the courses this contact has taken?" — One contact, multiple courses
- "What are all the vehicles this company owns?" — One company, multiple vehicles
- "What are all the subscriptions this customer has?" — One customer, multiple subscriptions
Use Custom Objects when the data represents its own entity with its own lifecycle, history, and status tracking—and you have multiple instances per customer.
How to Set Up HubSpot Custom Objects
Setting up Custom Objects requires an Enterprise subscription and Super Admin permissions. Once that's checked, follow these steps:
Step 1: Plan Your Implementation
Custom Objects are difficult to delete and rebuild. Thorough planning upfront prevents costly mistakes.
Planning checklist:
- Validate the 1:Many relationship
- Confirm this data truly needs multiple instances per customer. If tracking only one item per customer, use a custom property instead.
- Define your unique identifier
- Every Custom Object needs a primary display property. Examples: VIN for vehicles, License ID for subscriptions
- Map your associations
- Which standard objects will this connect to? Contacts? Companies? Deals? Tickets?
- Design your workflow triggers
- What actions will create new records? How will automation interact with this object?
- Create a flowchart
- Sketch the data model visually, define every relationship and dependency and map the direction of data flow
Pro Tip: Test everything in a sandbox or developer portal first. Deleting Custom Objects in production requires complex API work and causes major disruptions.
Step 2: Create the Custom Object
Once planning is complete, follow these steps:
- Access Custom Object Settings
- Navigate to Settings ⚙️→ Data Management → Objects → Custom Objects
- Create the Object Schema
- Click "Create custom object."
- Define singular and plural names (these are permanent—choose wisely)
- Add an internal description explaining the object's purpose
- Configure Display Properties
- Set the Primary Display Property (the unique field identifying each record)
- Configure up to three Secondary Display Properties for quick context
- These properties appear on record cards throughout HubSpot
- Finalize Object Creation
- Review your settings carefully
- Click "Create object"
- Set Up Associations
- Navigate back to object settings
- Configure associations with other objects (Contact, Company, Deal, etc.)
- Enable association cards to appear on linked records
- Create Properties
- Add all necessary properties for your data
- Apply validation rules: character limits, unique values, regex patterns
- Organize properties into logical groups
- Mark required fields
Step 3: Create Records
After setup, you can create records through five different methods:
- Manual creation: Navigate to the Custom Object index page and click "Create record."
- CSV import: Prepare a formatted spreadsheet and import records in bulk
- Workflow automation: Use "Create record" action in Enterprise workflows
- Form submissions: HubSpot forms can automatically create records
- API synchronization: Connect external systems via HubSpot API
Limitations of HubSpot Custom Objects
Custom Objects have four critical limitations you must understand before implementation:
1. No Email Personalization Tokens
Custom Object properties cannot be used directly as personalization tokens in marketing emails, sequences, or chat. This is the most significant limitation.
Let's say you store "Subscription Renewal Date" on a Subscription Custom Object. You want to send an email saying, "Hey , your subscription renews on ." That won't work directly.
The workaround:
- Create an Enterprise workflow
- Copy the Custom Object property value to a corresponding Contact property
- Use the Contact property as your personalization token in emails
It's extra work and creates additional properties, but it enables email personalization.
2. Limited Third-Party Integration
Many third-party integrations only support standard HubSpot objects, not Custom Objects. This includes platforms like Zapier.
What this means for you:
- Integrating Custom Object data typically requires custom API development
- You'll need dedicated development resources
- Implementation becomes more complex and technical
- Budget for additional development time and costs
3. Reporting Constraints
Certain specialized HubSpot reports only work with standard objects. This includes sales forecasts and deal attribution reports.
You can create custom reports for your Custom Objects, but you won't have access to all the pre-built reporting templates available for standard objects.
4. Scale Limits
You're limited to 1 million total Custom Object records across all object types in your account.
Scale considerations:
- High-volume transactional data (millions of log entries) may hit this limit quickly
- Consider alternatives like HubDB or external data warehousing for massive datasets
- Monitor your record count regularly to avoid hitting the cap unexpectedly
- The 1 million limit is shared across ALL your Custom Object types
Additional technical limits:
- Maximum of 10 properties can be designated as unique identifiers per object
- API rate limits apply (110 requests per 10 seconds for OAuth apps)
- Requires Enterprise subscription (significant cost barrier for smaller businesses)
Best Practices for Custom Objects
Six essential practices for successful Custom Object implementation:
1. Validate Your Need
Only create a Custom Object if you genuinely need a one-to-many relationship.
Decision framework:
- Can this be stored as a single property on a Contact or Company? → Use custom property
- Do you need multiple instances of this entity per customer? → Use Custom Object
- Is this data primarily for static website display? → Use HubDB instead
2. Choose Names Carefully
Object names are permanent and difficult to change. Use clear, descriptive singular and plural names.
Naming guidelines:
- Use descriptive, business-friendly names (not technical codes)
- Ensure proper singular/plural forms ("Subscription" / "Subscriptions")
- Avoid hyphens (they can interfere with personalization token generation)
- Make names intuitive for all team members
3. Document Everything
Use the description field to document the object's purpose, associations, and ownership.
What to document:
- The business purpose of this object
- Which teams use this object
- Intended associations with other objects
- The responsible team or person for maintenance
- Any special workflow dependencies
4. Enforce Data Quality
Leverage property validation rules to ensure clean data from the start.
Validation strategies:
- Enforce unique values for key identifiers (VIN, License ID, etc.)
- Set character limits to prevent data overflow
- Use regex patterns for formatted fields (phone numbers, emails)
- Mark critical properties as required fields
- Validate data, especially when records come from API syncs
5. Monitor Usage Regularly
Regularly review account limits, particularly total Custom Object record count.
Monitoring checklist:
- Check record count monthly against the 1 million limit
- Review property usage to avoid unnecessary custom properties
- Audit workflows that create or update Custom Object records
- Track API usage if syncing with external systems
- Watch for duplicate records or data quality issues
Ensure all end-users understand the object's purpose and proper usage before launch.
Training essentials:
- Explain what the Custom Object represents
- Demonstrate how to create and associate records
- Show where to find Custom Object data in the interface
- Clarify the difference between the Custom Object and Contact/Company data
- Provide written documentation and quick-reference guides
Common Mistakes to Avoid
Mistake #1: Wrong Primary Property
Problem: Choosing a vague or non-unique primary display property makes records impossible to search and identify.
How to fix it:
- Always use a clear, unique identifier as your primary property
- Examples: VIN for vehicles, License ID for subscriptions, Order Number for transactions
- Test searchability before rolling out to your team
- Make sure the primary property makes sense to all users, not just technical staff
Mistake #2: Missing User Permissions
Problem: Just because a Super Admin created the object doesn't mean everyone can see it.
How to fix it:
- Navigate to Settings → Users & Teams
- Edit the relevant permission sets
- Explicitly grant Read/Write access to the Custom Object type
- Verify permissions for each team that needs access
- Test with a non-admin user account before launch
Mistake #3: Improper Deletion Process
Problem: Attempting to delete a Custom Object directly from the UI without preparation causes failures.
Correct deletion process:
- Delete all workflow references to the Custom Object
- Delete all individual records of that object type
- Delete all custom properties on the object
- Then attempt to delete the object schema
- Often requires API commands for complete removal
Test thoroughly in a sandbox before deploying to production.
Mistake #4: API Integration Errors
Problem: Using incorrect API naming conventions causes integration failures. HubSpot assigns an internal prefixed name (like "p_dials") different from the UI name.
How to fix it:
- Use the schemas API endpoint to get the correct internal object name
- Always use the internal name in API calls, not the friendly UI name
- Implement proper error handling for 429 rate limit errors
- Use API batching for bulk operations
- Test API integrations in a development environment first
Custom Objects vs. Other HubSpot Tools
Choose the right data structure based on your specific needs:
|
Decision Factor
|
Custom Object
|
Custom Property
|
HubDB
|
|
Data relationship
|
1:Many (one company, many assets)
|
1:1 (one contact, one phone)
|
Independent rows (list of locations)
|
|
Primary use case
|
Complex, relational, transactional data
|
Simple, fixed attributes about a single entity
|
Static reference data for website display
|
|
Automation capability
|
Full workflow support for enrollment and status tracking
|
Used for segmentation and basic personalization
|
No workflow support; manual API/HubL access
|
|
Cost requirement
|
Enterprise subscription required
|
Professional or Enterprise
|
CMS Hub Professional or Enterprise
|
|
Typical volume
|
Hundreds to thousands of records
|
Unlimited (within property limits)
|
Hundreds to thousands of rows
|
Key Takeaways
- ✅ Custom Objects extend your CRM's data structure to match your unique business processes instead of forcing data into rigid categories.
- ✅ They solve the 1:Many relationship problem that custom properties can't handle—enabling you to track multiple instances of entities per customer.
- ✅ Enterprise subscription and Super Admin permissions are required to create and manage Custom Objects in your HubSpot account.
- ✅ Planning is non-negotiable because Custom Objects are difficult to delete and rebuild. Always test in sandbox environments before production deployment.
- ✅ Primary limitation: no direct personalization tokens in marketing emails, requiring workflow workarounds to copy data to Contact properties.
- ✅ Best use cases include: subscriptions, physical assets, course enrollments, and onboarding projects—anything where one customer has multiple associated instances.
- ✅ Record limit of 1 million total across all Custom Object types in your account requires monitoring and strategic planning.
- ✅ Integration typically requires custom API development for third-party tools, as many popular platforms only support standard HubSpot objects.
- ✅ Success depends on: thorough planning, proper training, data quality enforcement, regular monitoring, and clear documentation.
The Bottom Line
HubSpot Custom Objects represent a fundamental shift in CRM data management. They're a strategic tool for enterprise-level operations.
When implemented correctly, Custom Objects eliminate data silos, enable sophisticated automation, and provide teams with contextual information to drive growth. No more external spreadsheets. No more forcing complex data into categories that don't fit.
However, Custom Objects require discipline. They demand thoughtful planning, careful implementation, and ongoing management. Organizations that succeed invest time upfront to map data relationships, test thoroughly, and train their teams properly.
If you're running an enterprise operation with complex, transactional data that doesn't fit into Contacts, Companies, Deals, or Tickets—Custom Objects could be transformative for your business.
Are you ready to use this power strategically?
