Skip to content
Bryant WorksBook a Call

HubSpot architecture guide

What are HubSpot custom objects and when do you need them?

Chris Bryant, Founder

Updated Nov 2026

A HubSpot custom object is a record type you design for something contacts, companies and deals cannot hold cleanly. Policies, shipments and memberships are typical cases. You need one when that thing has its own properties, its own lifecycle and links to several other records. Map all three on paper before anyone builds it.

Book a Call
  • HubSpot Diamond Partner
  • 660+ client organizations
  • 330+ five-star reviews

Every CRM rests on a data model, the set of record types you track and the links between them. Contacts, companies and deals cover people, organizations and sales. Many mid-market teams track something else that matters as much. The design question is where that thing lives in your portal.

How a custom object fits your data model

A custom object adds a record type to your portal. Each record of that type carries its own properties. Each record can also link to contacts, companies, deals and other records through associations.

Suppose, as an imagined case, you run an equipment rental business. One company rents many machines over a year. Each machine has a serial number, a service date and a location. A deal records the rental. The machine needs a record of its own, linked to every company and deal that touched it.

The alternative is to stretch a standard record. Teams add machine fields to the company record, or they log each machine as a deal. Both choices break once one company holds many machines. Logging machines as deals mixes equipment into your sales pipeline and distorts every forecast built on it.

Signs your data needs a custom object

A custom object earns its place when the thing you track behaves like a record of its own. Check it against these conditions:

  • It exists in multiples per contact, company or deal, and each one needs its own values.
  • It has a status that moves over time, apart from the sales stage.
  • It links to more than one kind of record, such as a contact and a company at once.
  • Your team reports on it as a unit, such as counting active policies or open shipments.
  • It outlives the deal that created it, such as a membership that renews each year.

When the thing meets only one condition, a property usually covers it. A single value per record, such as a contract end date, stays a property. A custom object adds a record type that your team has to learn, maintain and report on. That cost requires a clear case.

Test Use a property Use a custom object
Count per record One value per record Many records per parent
Stages over time No stages of its own Moves through its own stages
Links to other records Lives on one record Links to several record types
How you report Filtered as a field Counted and grouped as records

How custom objects relate to contacts, companies and deals

Associations carry most of the value in a custom object. A policy record with no link to its holder answers nothing. The same record linked to a contact, a company and the renewal deal tells you who holds it, who pays for it and what renews next.

Plan each association by naming the two record types and the count on each side. One company can hold many policies. One policy can name several contacts, such as a buyer and a billing contact. Write these pairs down before the build. They decide which reports and workflows your team can run later.

Associations also shape daily work. A rep who opens a company needs to reach its policies from that record. When the link is missing, the rep goes back to a spreadsheet, and the portal loses another user.

What to plan before you build

We design custom objects together with the associations, property sets, pipelines and board views around them. Our HubSpot custom builds start from your data model and work outward. The plan covers four parts:

  • Properties. List each field the object needs, its type and who fills it in.
  • Associations. Name every record type it links to and the count on each side.
  • Pipeline. Define the stages, if the object moves through any, and the event that moves a record forward.
  • Reports. Write the questions leadership will ask, then check that the design answers each one.

Reports belong on the list because they test the design. Suppose a leader asks for renewals by region, and region sits on an object with no link to renewals. That report fails. Fixing it after launch requires changes to properties, associations and the records already loaded.

HubSpot has awarded us its Solutions Architecture Design accreditation. It covers solution design that starts at the data model and extends to the systems connected to it. Our credentials page lists it beside our Onboarding and Custom Integration accreditations.

Custom objects in a migration from another CRM

Many custom objects start life in another system. Teams moving from Salesforce, Zoho or a homegrown tool often bring record types they built themselves over years.

During a CRM data migration, we match each custom object and its properties in the old system to a counterpart in HubSpot. We keep the links between records intact, so a policy still points to its holder after the move.

The migration also tests the design. Our audit of the old CRM shows which record types your team still uses. Unused ones can stay behind with the archived data. A record type that repeats what a contact or company already holds can fold into that standard object.

A CRM data migration typically runs 6 to 12 weeks. Records move in controlled batches. We then validate the moved data against your old system before handoff.

Where custom objects stop helping

A custom object fixes a modeling problem. Dirty data and an unsettled process survive it. If reps log policies three different ways today, the new object stores three different ways. Before a load, we deduplicate records and normalize field values.

This guide does not list HubSpot’s limits on custom objects or the subscriptions that include them. Those terms come from HubSpot, so confirm them on HubSpot’s current pages before you design.

Custom builds typically run 8 to 16 weeks. Our implementations, custom-object builds included, end with documentation of what was built and why. New admins read that record before they add a field or a link.

Common questions

How do you create custom objects in HubSpot?

You start by writing down the object's properties, the record types it links to and any stages it moves through. The build follows that design, and the steps inside the portal depend on HubSpot's current tools. We build custom objects as part of our custom builds, which typically run 8 to 16 weeks.

Which HubSpot tools work with custom objects?

This guide does not list them, because HubSpot sets that support and changes it with the product. Confirm it in HubSpot's current documentation for each workflow, list and report you plan to run. A design that depends on an unsupported tool breaks after launch, so check before the build starts.

What are the limits on HubSpot custom objects?

HubSpot sets the limits on custom objects, and this guide does not state them. Check HubSpot's current pages for your subscription before you design anything. A design with fewer objects stays easier to maintain under any limit.

What are some examples of HubSpot custom objects?

Typical examples include insurance policies, shipments, memberships, property listings and equipment units. Each one exists in multiples per company or contact and needs its own fields. Many also move through stages, such as a policy that goes from quoted to active to renewed.

Let's scope it together.