The HubSpot properties every B2B portal should document, and how

The three fields

Description, data entry instructions and option descriptions: three fields, three jobs. Open any property, edit it, and look at the documentation section.

Property description. Shown to users directly on the record. One or two plain sentences saying what the field is and why it matters.

Data entry instructions. How the property should be filled in, by people and by anything that writes to it. This is the most important field for accuracy, and the right place for rules, edge cases and explicit exclusions. Since HubSpot's August 2026 release it can be added to any property, and it surfaces on the record, at creation and in column headers.

Option descriptions. Only appears on enumeration types: dropdown, radio, checkbox. One line per option, saying what the value means and when to pick it.

One practical note that saves an afternoon. The description is writable through the properties API, so you can set it in the same call that creates the property. Data entry instructions and option descriptions are UI-only at the moment, which means they have to be pasted in. Write them as copy-paste content alongside the build rather than promising yourself you will come back.

Which properties to document first

Document the fields people misread most, first. You are not going to document 400 properties, and you should not. Work in this order.

1. Lifecycle stage. The single most misused field in HubSpot. Write the entry criterion for each stage into the option descriptions and you have solved most of the recurring confusion about it.
2. Lead status. Second most misused, and almost always inherited from a default nobody reviewed.
3. Original source and its drill-downs. People misread these constantly, and a one-line description on the record is the cheapest fix for the wrong reports that follow.
4. Deal stage. What has to be true to enter it, per stage, in the option descriptions.
5. Every custom enumeration a human picks from. Industry, service line, account type, request reason. Any field where somebody has to choose between two plausible options.

Then, on an ongoing basis, every new custom property at the moment you create it. That rule is cheap if you hold it and expensive to retrofit if you do not.

What you can safely skip: native fields that are self-evident, calculated properties whose formula is the documentation, and anything you are about to retire.

What good documentation looks like

The three fields have three different jobs and the most common mistake is writing the same thing in all of them.

The description is for a person

It appears on the record where a rep will read it mid-task. So: plain language, one or two sentences, what the field is and why it matters. As long as necessary, as short as possible.

Things that do not belong in it: the internal property name, capitalized emphasis, and scaffolding like "note that it does NOT include." Those are rules, and rules go in the next field.

Business Type. The primary classification of this company's relationship with your organization. Drives how the team engages with it, whether as a client being served, a vendor being paid, or a partner being collaborated with.

The data entry instructions are for accuracy

This is what a new hire reads when they are unsure, and the most useful thing you can give any tool that populates the field. Be explicit. State the rule, name the edge case, say what not to do.

Select the single type that best describes how your organization primarily works with this company. If the company has more than one kind of relationship, for example a vendor who is also a partner, set this to the dominant relationship and capture the rest in the secondary relationship property. Never duplicate the primary type in the secondary field.

That last sentence is the one that earns its place. Explicit exclusions are the highest-value thing you can write here, because they are the decisions that otherwise get made differently by every person and every model.

The option descriptions are for the choice

One concise line per option. The job is to make the boundary between two adjacent options obvious.

• Prospect. A company being actively pursued as a potential client. No active contract yet.
• Partner. A company with a formal or informal partnership arrangement: referral, solutions, technology or co-sell.
• Vendor. A company you pay for a product or service.

If two of your options need a paragraph each to distinguish, that is worth noticing. It usually means the options themselves need merging.

A convention worth adopting: write it portal-agnostic

Write every description as "your organization" rather than naming the company. Small discipline, large payoff.

Do that and the documentation for a property set you build once becomes reusable on the next portal unchanged. We keep a registry of documented property sets for exactly this reason, and the only thing that makes a set promotable is that it was written generically the first time.

Two conventions we hold on every portal

Custom property labels use Title Case. First word, last word and all major words capitalized. Articles, coordinating conjunctions and short prepositions stay lowercase unless they land first or last. Acronyms stay uppercase. "Show in Client Workspace," "Completed by Client At," "Workspace Task ID."

That applies to properties you create. Native HubSpot fields keep the casing HubSpot ships, partly because several of them cannot be renamed anyway. The same Title Case rule covers custom report and dashboard names, which drift faster than properties do because nobody audits them.

Documentation is part of creating the property, not a later pass. This is the rule that actually matters, and it is the one most teams agree with and then do not hold. A property created without a description is a property nobody can safely retire in two years, because nobody can establish what it was for, or what still reads it.

We have seen what that costs. In one portal, a form redesign retired a source property and replaced it with a cleaner one. The form was updated; a workflow that still read the old field was not. For about six weeks new leads arrived with a blank source, with no error anywhere. HubSpot's own archive check would have listed several dependencies where a check of forms alone found two, but it does not list reports or properties that mirror the retired one. The fix is a migration checklist run at the start of any property change, not the end, and a description that says what the field feeds makes that checklist far shorter.

Why this stopped being a tidiness issue

It stopped being a tidiness issue when HubSpot's own features started writing to your records. In the Fall 2026 release, the CRM can propose property updates from calls, emails and meetings, each cited to its source, and those updates flow into workflows and segments. HubSpot has not published exactly which documentation fields its agents read, so treat this as our working assumption, not documented behavior: anything asked to populate a field or pick an option does better with written rules than with a label. Give it nothing and it infers from the label, which is exactly as reliable as it sounds.

The compounding version of this argument is that your CRM's real value is the context it accumulates, and undocumented context is not context. It is data nobody can interpret, including the thing you bought specifically to interpret it.

When to skip this

Do not spend a week on this if the portal is about to be rebuilt or migrated, or if you have a few dozen properties and the person who built them still works here. Document the five groups above and stop. Documentation also does not rescue a bad design: if two options need a paragraph each to tell apart, merge them instead of describing them.

Where to start

Count how many of your custom properties have no description at all. In the two portals we audited in August 2026, it was about half of one portal's custom contact properties and about a third of the other's custom properties. The first also carried around twenty fields with garbled internal names, generated automatically from long form questions, which no description can rescue after the fact. If you want that number across every object, plus the list of properties duplicating a native field, that is dimension three of a HubSpot Portal Audit.