HubSpot CRM Data Model: Objects, Properties and Associations

A HubSpot CRM data model should keep independently managed work in separate records, facts on the record they describe, and relationship context on the relevant association. Use a Deal for each opportunity, Company properties for account facts, and Contact-to-Deal associations for opportunity-specific participants. Add a custom object only when a supported standard object or labeled relationship cannot represent the required work.

A sales manager asks how many opportunities are open at an account. Operations needs the procurement contact for one of them. An integration has just added the same person to a second company. If the CRM stores opportunity stage on the Company and buying role on the Contact, these ordinary questions produce conflicting answers.

This guide gives CRM owners and RevOps teams an eight-step implementation sequence, a fictional two-deal example and a downloadable field dictionary. Examples in this guide use fictional companies, people and numbers.

1. Define what one record represents

Before opening settings, finish this sentence for every object: “One record represents one…” This is the model's grain, the unit you will create, update and count.

HubSpot distinguishes objects, records, properties and associations. An object is a type of business information; a record is one instance. A property stores a fact on that record. An association connects two records.

On smaller screens, scroll to compare all columns.

Ask whether the fact can have several simultaneous values. “Contract end date” on a Company becomes ambiguous when three contracts end on different dates. A Company summary such as “next renewal date” can still be useful, but define which underlying records determine it and who refreshes it.

Also separate current state from history. A current job title answers what is believed now. It does not by itself represent every employment period or explain who approved each change.

2. Draw a small example before configuring the portal

The .example domains are documentation placeholders. Stages, labels and sample_ properties are proposed custom configuration.

On smaller screens, scroll to compare all columns.

P-10 works for C-100 and advises C-200. P-20 works for C-100. Both opportunities belong to C-100. P-10 sponsors D-101 and is the technical reviewer on D-102; P-20 is D-102's procurement contact.

The example is deliberately small enough to inspect record by record. Add a difficult example from your own process before scaling: a missing buyer, a second open opportunity, or a person with two company relationships. A model that only works when every account has one contact and one deal is incomplete for this use case.

3. How should HubSpot associations and the primary company work?

Keep “Technical reviewer” on the P-10-to-D-102 relationship. A Contact property called “Buying role” would lose the distinction between that role and P-10's sponsor role on D-101. Similarly, D-102 entering Contract review must not change D-101's Evaluation stage.

HubSpot association labels describe relationships and can be used in compatible workflows and reports. Custom labels require an eligible Professional or Enterprise subscription and Super Admin creation permissions. The object pair must support them. Define the direction too: “Employee” describes the contact's side; “Employer” could describe the company's side of a paired label.

The intended relationship map includes:

• P-10 → C-100: Employee, with C-100 primary.
• P-10 → C-200: Advisor, with C-200 non-primary.
• P-20 → C-100: Employee, with C-100 primary.
• D-101 and D-102 → C-100: company associations, with C-100 primary for each deal.
• P-10 → D-101: Business sponsor.
• P-10 → D-102: Technical reviewer; P-20 → D-102: Procurement contact.

The primary company affects automatic activity association and is referenced by cross-object tools. Relevant lifecycle synchronization settings also use it. HubSpot defaults the first company associated with a contact to primary. Set the intended primary explicitly during setup and check it after imports or integration changes.

If custom labels are unavailable, retain ordinary associations and a separate relationship register with the two record keys and role. Use a manual handoff until the intended relationship can be evaluated reliably. A free-text role without a company or deal key cannot tell the process which relationship it describes.

4. When should you create a HubSpot custom object?

“Advisor at Bridge Advisory” is enough for the current example. The requirement changes if the team needs an advisory agreement from January to September, a renewal from October to March, different owners, and an audit of which agreement was active at a given date.

In that extended example, propose one Engagement record per agreement period. E-301 could connect P-10 and C-200 with start date 1 January 2026, end date 30 September 2026 and status Completed. E-302 could connect the same records with start date 1 October 2026, end date 31 March 2027 and status Active. These are additional design examples, outside the six-record example in the download.

The relationship's dates now belong to an independently identifiable agreement. Storing both periods in “Advisor start 1,” “Advisor start 2” and similar Company fields would impose an arbitrary limit and make renewal reporting awkward. A label alone does not carry the agreement's dates, owner and status.

Before approving a custom Engagement object, check HubSpot's standard objects and tool compatibility. A supported standard object may already match the process. Do not use a Deal merely as a convenient container for non-commercial history if that would inflate opportunity counts.

Custom objects require Enterprise. Confirm capacity, permissions, required associations and the reporting/workflow operations you need. Approve an owner, identity rule and retention rule. If the portal cannot support the requirement, retain the detailed agreements in their source system and define a limited CRM summary instead. The original current-role example does not need a custom object.

5. Write the field dictionary and ownership rules

Use an existing standard property when its definition fits. HubSpot's property guidance recommends checking defaults first; custom-property limits depend on subscription. New custom properties can be empty unless a default is configured. Decide whether blank means unknown, not applicable or awaiting review.

The download contains a full dictionary. These rows show the level of definition needed before approving writes:

On smaller screens, scroll to compare all columns.

For each field, record the internal name, type, accepted values, source, refresh trigger, overwrite rule and exception owner. Internal names and selected object cannot be changed after creation, so review them before setup. A dropdown's display label and internal option value also need an explicit mapping.

Keep research proposals separate from commercial authority. Clay enrichment may propose account facts; it should not independently change deal amount, stage, owner or a contact's primary company. The Clay and HubSpot integration guide explains controlled writeback, and the enrichment guide covers accepting proposed values.

Naming a responsible writer in a dictionary documents the process. Configure and verify the actual user permissions, integration credentials and write behavior separately.

6. Map the design to the actual HubSpot configuration

Implement in an authorized test environment or controlled test process before production automation. Capture the relevant existing properties, stages, labels and integration mappings first so the change can be reviewed and reversed.

1. In Settings → Properties, select the intended object. Reuse matching defaults, then create only the approved custom properties. Confirm internal names, field types, options and blank rules. Property creation requires the appropriate property-settings permissions.
2. In Data Management → Data Model, review the object relationships. For eligible accounts, create approved association labels through the data model editor. Record both directions of paired labels and confirm the intended object pair.
3. Resolve the actual pipeline and stage identifiers. “Evaluation” and “Contract review” in this article are readable example labels. Use the resolved identifiers in API calls.
4. Create or identify the six authorized test records, then capture their real HubSpot Record IDs. Apply the eight relationships in the mapping file and inspect primary-company choices.
5. Check the saved records and associations. Check that every external key maps to one intended record before connecting a writer.

C-100, P-10 and D-101 are diagram keys. HubSpot assigns real record identifiers; its deal-property documentation describes the Deal Record ID used for updates. Keep a crosswalk between sample/source keys and the real portal IDs. Never populate a Record ID field with these diagram labels.

The CSV pack is a design and acceptance reference. It leaves portal IDs and configuration IDs unresolved. An import requires a reviewed mapping, actual properties and labels, and a decision about creating versus updating records. Use the CRM migration checklist for that separate process.

7. Validate the handoff from the record that owns it

For the example, start the implementation review from D-102 because its buying motion and stage define the work. HubSpot workflow creation requires an eligible subscription and permissions; the available object types and actions vary. Confirm that the intended branch and action can evaluate the required association label.

Write the rule before configuring it: “When an Implementation deal enters Contract review, identify its primary company and exactly one Procurement contact. If either is missing or ambiguous, route an exception for review. Otherwise request the defined procurement review for the deal owner.”

On smaller screens, scroll to compare all columns.

These are acceptance expectations. Record actual enrollment, branch selection, affected IDs and resulting action when testing. Keep workflows unpublished until the relevant checks pass. Closing D-102 also needs its own policy; it does not authorize copying its stage to D-101 or rewriting every contact's lifecycle stage. See the B2B lifecycle-stage guide for that decision.

8. Reconcile reports to records before trusting totals

For a fixed example reporting date of 9 October 2026, both deals are open. Expected results are two opportunities totaling EUR 30 000, one in each proposed stage, and one company with open opportunities. All companies in the example total two. Those are different populations.

HubSpot's custom report builder lets eligible accounts select a primary data source, additional sources and association labels. Creation also requires report permissions. Start an opportunity report with Deals as the primary source; add other sources only when the question needs them.

On smaller screens, scroll to compare all columns.

An exported Deal-to-Contact join may produce three rows: D-101/P-10, D-102/P-10 and D-102/P-20. Summing each row's amount would produce EUR 36 000. The desired opportunity total still counts each Deal once and remains EUR 30 000. Inspect the report's record details, filters and aggregation; do not assume every HubSpot chart duplicates values in the same way.

State the unit, reporting date, pipeline, open-stage definition, currency and association scope in the report specification. Confirm how unmatched records appear. The sample uses one currency and proposed Deal Amount. Weighted pipeline, MRR, ARR, signed revenue and collected cash are separate measures. HubSpot documents different deal-value properties; choose the one that answers the actual question.

Download the model and adapt it to one real process

Download the CRM data model reference pack (ZIP). It contains six CSV files: a field dictionary, Companies, Contacts, Deals, the eight-row relationship map, and expected report/workflow checks. The README explains diagram keys, real IDs, unresolved configuration and how to use the pack without treating it as an import template.

For a model review, replace the fictional scenario with one sanitized handoff and one report your team cannot currently trust. Agree on the record grain, dictionary, relationships and expected results before configuring automation. Review duplicate identity separately with the HubSpot deduplication guide.

AGI Technologies' HubSpot development and RevOps service can scope that review around the account structure, concurrent opportunities, current writers and required decisions. Discuss the CRM review.