HubSpot Property Architecture: Designing Fields That Stay Clean

What is property architecture in HubSpot?

Property architecture is the set of decisions about which facts your HubSpot portal stores, on which object, in which field type, and who or what is allowed to change them. Properties are the fields on contacts, companies, deals, tickets and any custom objects. Get the architecture right and your segments, workflows and reports become simple to build. Get it wrong and every one of them needs a workaround.

Most portals don’t have an architecture. They have a history. Someone needed a field for a campaign in 2021, someone else needed a similar one in 2023, and an integration added fifteen more. This guide is about designing deliberately, in a new portal or one you’re cleaning up. For governance practices that apply on any platform, see our CRM property governance guide.

Start with the question, not the field

Before creating a property, write down the question it will answer and who will ask it. “Which industry is this company in?” is a question. “Industry field for webinar form” is not.

Then check whether HubSpot already answers it. HubSpot ships with a lot of default properties: Lifecycle stage, Lead status, Original Traffic Source, Last contacted, Number of sales activities, owner fields and dozens more. Many portals contain custom fields like “Lead Source” that duplicate what HubSpot already tracks, then disagree with it.

A useful test: if you can’t say which segment, workflow or report will use a new property, don’t create it yet.

Which object should a property live on?

Put a property on the object it describes. That sounds obvious, but it’s the most common architecture mistake we see.

• Contact: facts about a person. Job title, role in the buying decision, communication preferences, personal lifecycle data.
• Company: facts about the organization. Industry, employee count, region, customer tier, contract renewal date.
• Deal: facts about one buying event. Product, amount, close reason, competitor, contract length.
• Ticket: facts about one support request.

Here’s how it goes wrong. A B2B company adds “Industry” to the contact object because their form asks for it. Two years later, a company has five contacts with five different industries, because each person typed something slightly different. Reports by industry are useless. Industry belongs on the company, and the form answer should be used to fill the company field (or ignored if enrichment already provides it).

The same applies to “Product purchased” on contacts. If someone can buy more than once, purchase data belongs on deals or a custom object, with summary values rolled up to the contact or company.

Custom objects, which need an Enterprise subscription, are worth considering when you track something with its own lifecycle that doesn’t fit a deal or ticket: subscriptions, properties for a real estate firm, locations for a franchise. They aren’t a fix for poor use of standard objects.

Choose the right field type

Field type decides what data the property can hold and how usable it is in filters. HubSpot’s main types at the time of writing:

• Single-line text and Multi-line text: free text. Easy to fill, hard to report on.
• Dropdown select and Radio select: one option from a fixed list.
• Multiple checkboxes: several options from a fixed list.
• Single checkbox: yes or no.
• Number, with formatting for currency, percentage and more.
• Date picker and Date and time picker.
• HubSpot user: one or more users, useful for extra owner-style fields.
• Calculation, Rollup and Property sync: values HubSpot works out for you (more below).
• File, URL, Rich text, Email and Phone number for specific formats.

The rule of thumb: if you’ll ever filter, segment or report on it, use an option-based type instead of text. A text field called “Country” will contain “UK”, “U.K.”, “United Kingdom”, “england” and “Great Britain”. A dropdown can’t.

Changing a field type later is possible but risky. Converting text to a dropdown creates an option for every unique value, so “LinkedIn”, “linkedin” and “linked in” become three separate options you then have to merge. Values may become invalid, and changes can take time to apply across the account. Export the data before you convert. You also can’t convert a property to or from a calculation type.

For dropdowns, the internal value of each option matters as much as its label. Workflows, imports and integrations often use the internal value. Keep internal values stable and change labels instead when wording changes.

Name properties so people can find them

Internal names can’t be changed after a property is created, and neither can the object it belongs to. So the first naming decision is permanent.

A few conventions that work:

• Use the label people will search for. “Renewal date”, not “RD” or “Contract_end_v2”.
• Don’t put the year, campaign or person’s initials in the name. If a property only makes sense for one campaign, it probably belongs in a static segment or a campaign-specific form field you archive afterward.
• Prefix integration-owned fields with the system name, for example “Stripe – Plan” or “Shopify – Total orders”, so everyone knows not to edit them by hand.
• Write a description for every custom property. Say what it means, what fills it, and who owns it.

Use property groups for findability

Property groups organize properties in settings so they’re easier to find and manage. You create and edit them in Settings > Properties, on the Groups tab for each object, and move properties between them individually or in bulk.

Groups appear in property settings only. To control which properties people see on a record, configure record sidebars and cards separately. So groups are for the people who maintain the portal, not for reps.

A grouping that works for most B2B portals: Identity and contact details, Firmographics, Lifecycle and qualification, Ownership and routing, Marketing attribution, Product and usage, Billing and contract, and one group per integration. The integration groups are particularly useful. When an integration is removed, you can see every field it created in one place.

Use calculated properties instead of manual copying

Calculated properties let HubSpot work out a value from other data, so nobody has to type or copy it. They need a Professional or Enterprise subscription. The main options at the time of writing:

• Rollup: aggregates values from associated records with Min, Max, Count, Sum, Average, Earliest date or Latest date, with optional conditions. “Total closed won revenue” on a company, or “number of open tickets”.
• Time between, Time since and Time until: durations between dates, with an option to exclude weekends for time between. “Days from MQL to SQL”, or “days until renewal”.
• Custom equation: a formula using properties of the same object, returning a number, text, true/false, date or option value.
• Property sync (a separate field type): copies a property from an associated record and keeps it updated, such as copying the company’s customer tier onto each contact.

A few caveats worth knowing. If any number in a custom equation is empty, the whole result is empty, so wrap inputs to default to zero where that makes sense. Durations are stored in milliseconds, which matters when you filter on them. Time since and time until can’t be used in custom report filters or as inputs to other calculations. Calculation properties can’t be used in forms. And there are limits on how many calculation properties each subscription allows, so spend them on values people actually use.

The payoff is real, though. A rollup or property sync replaces a workflow that copies values on a schedule, and it can’t fall out of date because someone switched the workflow off.

Decide who can change each property

Every important property should have one source of truth: a person, a form, a workflow, or an integration. When two of them write to the same field, the value depends on which ran last.

HubSpot gives you some tools for this. The Usages tab on a property shows where it’s used in the CRM. The Rules tab can add validation, such as blocking special characters, depending on field type. And the Manage access tab, where your subscription includes it, can restrict which users and teams can view or edit a property, which is useful for fields like contract value that only finance should touch.

For integration fields, the bigger decision is sync direction. If billing owns “Plan”, the HubSpot field should be read-only for people and never written by workflows. Our CRM data dictionary template has a column for exactly this.

Clean up what’s already there

If you’re inheriting a portal with hundreds of custom properties, don’t start by deleting. Start by measuring.

1. Export all properties. The export from property settings includes fill rate and usages for each property, across the objects you choose.
2. Sort by fill rate. Properties under a few percent filled are candidates for archiving, unless they’re new or deliberately sparse.
3. Look for near-duplicates. “Lead Source”, “Lead source (new)”, “Source” and “Original Lead Source” usually tell a story. Pick one, migrate the values, and update the forms and workflows that write to the others.
4. Check dependencies. When you archive a property, HubSpot shows the fill rate, the assets preventing archiving and other assets using the property. Properties used by workflows, segments, forms or property cards may be blocked until those references are removed.
5. Archive, then wait. Archived properties can be restored from the Archived tab. After 90 days they’re removed permanently.

Work through it in batches by group. Archiving forty properties at once makes it hard to tell which one someone actually needed.

A short checklist

• Every custom property answers a stated question and has a description.
• Properties sit on the object they describe.
• Anything used for filtering or reporting is option-based, not free text.
• Integration fields are prefixed, grouped and protected from manual edits.
• Values that can be derived use rollups, calculations or property sync, not copy workflows.
• Each important property has one source of truth.
• Fill rate and usage are reviewed at least once a year.

If you’re planning a bigger cleanup, our CRM data cleanup guide covers deduplication and value standardization alongside the property work.