Skip to content
SolutionArg

Data

HubSpot Custom Objects: When You Need Them (and When You Don't)

A plain-English guide to HubSpot custom objects: when they beat properties or standard objects, what plan you need, and how to design one that lasts.

By SolutionArg7 min read

TL;DR

  • A custom object is a new record type in HubSpot (for example Vendor, Work Order, Vehicle) with its own properties, associations and records.
  • You need one when the "thing" you track exists many times per contact, company or deal, has its own lifecycle, and you need to report on it or automate around it.
  • You do not need one when a few extra properties, an existing standard object (products, listings, tickets) or an association label already does the job.
  • Creating custom objects requires an Enterprise subscription (HubSpot KB). Decide the data model before you buy the upgrade.

Why this decision matters more than it looks

Most HubSpot portals start with the same four building blocks: contacts, companies, deals and tickets. That covers a lot. But sooner or later a business hits something that doesn't fit: a property manager has vendors and work orders, an equipment dealer has serial-numbered machines, an agency has projects that outlive a single deal.

The usual first reaction is to cram that data into more properties on the deal or the contact: "Machine 1 serial", "Machine 2 serial", "Machine 3 serial". It works for a week. Then someone has a fourth machine, reports stop adding up, and workflows can't tell which machine a renewal belongs to.

A custom object fixes that by turning the "thing" into its own record type, which is linked (associated) to the contacts, companies and deals it relates to. The cost is real, though: an Enterprise plan, more design work up front, and one more object for your team to understand. So the question is never "can we build a custom object?" It's "is this data really its own thing?"

The 4-question test

Answer these about the data you're trying to store:

  1. How many per record? If each company has exactly one value (for example, "ERP customer number"), that's a property. If each company can have several of them, each with its own details, you're looking at an object.
  2. Does it have its own lifecycle? A work order that moves from Open to Scheduled to Completed while the contact stays the same is a strong signal.
  3. Do you need to report or automate on it directly? For example, "show me all open work orders older than 7 days" or "when a vendor's insurance expires, notify the owner".
  4. Is it related to more than one standard object? A vehicle that belongs to a contact, a company and several service deals is hard to model any other way.

If you answered "yes" to 1 plus at least one other question, a custom object is usually justified. If you answered "no" to 1, stop and use properties.

Check the alternatives first

Before you upgrade to Enterprise, rule out these cheaper options:

  • Custom properties. Available from Starter upwards, with limits that depend on your subscription (HubSpot KB — CRM data limits). They're best for single values per record.
  • Association labels. These describe how two records relate (for example, "Billing contact" vs "Decision maker"). They're available on Professional and Enterprise (HubSpot KB — CRM data limits). Sometimes the "new object" you wanted is really a relationship type.
  • HubSpot-defined objects you haven't switched on. HubSpot ships objects beyond the basic four. For example, Listings store "a particular property or unit to be bought, sold, or rented" and must be activated in the account (HubSpot Listings API). The data model builder shows which objects your account has and lets you activate or deactivate them (HubSpot KB — data model builder).
  • Products and line items. If you're modelling things you sell on deals, the product library usually wins.

When I've used custom objects

In one integration I built with Make, Rentvine vendors and work orders were stored as custom objects in HubSpot. Webhooks created and updated them automatically, and activity data was exported back so the team had one view. That passed the 4-question test easily: many work orders per property owner, each with its own status, and the team needed to report on them.

The other side matters just as much. Many requests I see for "a custom object" turn out to be two or three properties plus a well-named association label.

How to design a custom object that lasts

1. Write the model on paper first

List the object name (singular and plural), the 5–15 properties that matter, the primary display property (what shows as the record name), and every object it must associate with. HubSpot's schema guide asks for exactly these pieces when you define an object: its name, properties and associations (HubSpot Schemas API).

2. Pick a unique ID from the source system

If records come from another system (ERP, property management tool, booking engine), store that system's ID in a property marked as a unique identifier. You'll use it later to update records without creating duplicates (see the upsert section below).

3. Check your limits before you build

Custom object limits depend on your subscription. The schemas guide points to the HubSpot Products & Services catalog for the numbers (HubSpot Schemas API). You can also check your current usage through the limits tracking API (HubSpot limits tracking).

4. Create it in the UI or via API

You can create the object in HubSpot's data model settings (Data Management > Data Model) (HubSpot KB). If you work across sandboxes or several portals, the API is more repeatable.

5. Build one report and one workflow before migrating data

If you can't produce the report that justified the object, fix the model now. It's much harder to change after 10,000 records exist.

Technical depth: the custom objects API (2026-09)

HubSpot moved its REST APIs to date-based versions; the current version at the time of writing is 2026-09 (HubSpot API versioning). All paths below come from HubSpot's current docs.

Define the schema

POST /crm-object-schemas/2026-09/schemas

The request includes the object's name, labels, properties and associations. By default, properties created through the schema request use type: string and fieldType: text unless you specify otherwise (HubSpot Schemas API).

Create, read and update records

POST /crm/objects/2026-09/{objectTypeId}
GET  /crm/objects/2026-09/{objectTypeId}/{recordId}?properties=year&properties=make

Batch versions exist for read, create, update, upsert and archive (HubSpot custom objects API).

Upsert with your unique ID

The upsert endpoint creates records that don't exist and updates the ones that do, keyed on a unique identifier property (HubSpot custom objects API):

POST /crm/objects/2026-09/{objectTypeId}/batch/upsert

{
  "inputs": [
    {
      "id": "1D7HU18Z42S598204",
      "idProperty": "VIN",
      "properties": { "price": "4000" }
    }
  ]
}

This is the single most useful pattern for syncs: your integration never has to ask "does this record already exist?" first.

Associate records

PUT /crm/objects/2026-09/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}/{associationType}

To find the associationType value for an object relationship you've defined, read the schema with GET /crm-object-schemas/2026-09/schemas/{objectType} (HubSpot Schemas API).

Search has its own limits

The CRM search endpoints are useful for lookups, but plan around their limits (HubSpot CRM search):

  • five requests per second per account;
  • up to 200 records per page;
  • a maximum of 10,000 total results per query;
  • up to five filterGroups with up to six filters each, and 18 filters in total.

Respect rate limits

For privately distributed apps, burst limits are 100 requests per 10 seconds on Free/Starter and 190 on Professional/Enterprise. Daily limits are 250,000, 625,000 or 1,000,000 requests per account depending on tier. HubSpot recommends batch endpoints and caching to stay under them (HubSpot usage guidelines).

Common mistakes

  • Building the object before the report. If the report isn't possible, the model is wrong.
  • No unique ID. Without one, every re-sync risks duplicates.
  • Mirroring every source field. Bring over what sales, service or reporting will actually use.
  • Ignoring permissions. Decide who can see and edit the new object before launch.

Sources

FAQ

Do I need Enterprise for custom objects? Yes. Creating custom objects requires an Enterprise subscription of one of HubSpot's hubs, Smart CRM or Revenue Hub (HubSpot KB).

Can I update custom object records without creating duplicates? Yes. Use the batch upsert endpoint with a unique identifier property as idProperty (HubSpot API).

How many custom objects can I create? It depends on your subscription. HubSpot points to its Products & Services catalog for the numbers, and you can check usage through the limits tracking API.

Is a custom object better than more properties? Only when the data exists many times per record, has its own lifecycle, or needs its own reports and automation.

Let's find the manual work hiding in your HubSpot.

30 minutes. You show me how things work today; I'll tell you what I'd fix first and roughly what it takes — no pitch deck.

Send a messageSee case studies

Almost always reply within 24 hours