HubSpot property naming conventions: a template for internal names, groups and labels

By Kayabyte

Short answer: decide the internal name first, because HubSpot does not let you change it after the property is created (“you cannot edit the property’s object type or internal name”, HubSpot guide). Labels, groups and descriptions can be changed later, so be consistent but don’t agonise over them.

Portals get messy when each person names fields their own way: “Industry”, “industry_2”, “Company Sector (new)”. A short written convention, applied before properties are created, avoids most of it. This guide gives you one to copy.

What you can and cannot change later

Part	Visible where	Change later?
Object type	Settings	No
Internal name	Workflows, reports, imports, API, integrations	No (HubSpot guide above)
Label	Records, forms, reports	Yes, in the property’s Details tab
Group	Property settings	Yes, move a property to another group (HubSpot guide)
Description	Property settings	Yes
Dropdown option labels and values	Records, imports	Labels yes; check your import file for how values are handled

HubSpot also notes that some properties can’t be edited, including certain default properties and properties in use on records or in tools such as segments or workflows. If you realise an internal name is wrong, the fix is a new property, a move of the values, and archiving the old one (archived properties are deleted permanently after 90 days; HubSpot guide). See how to audit and clean up properties.

A template you can copy

Internal names

Lower-case letters, numbers and underscores only; start with a letter.
Pattern: <area>_<what> with the most general word first, so related fields sort together: finance_payment_terms, finance_po_number, onboarding_kickoff_date.
Do not start a name with hs_: HubSpot reserves that prefix for its own properties.
Say what it is, not who asked: renewal_date, not jos_date.
No version or temporary words: avoid _new, _old, _2, _test.
Booleans and dates: end dates with _date, yes/no fields with a clear question such as is_partner or has_signed_dpa.
Dropdown option values: short, lower-case and stable (enterprise, mid_market), with the friendly text in the option label. Values are what workflows and reports compare against.
Keep names under 100 characters. HubSpot’s own articles don’t state these character rules in one place, so we follow the rules our import app and the free checker apply; HubSpot’s API will tell you if a name is not accepted.

Labels

Sentence case, no abbreviations your newest rep wouldn’t know: “Contract start date”.
Put the question in the label for dropdowns and the unit in the label for numbers: “Contract length (months)”.
Do not put the object or the group into the label (“Deal contract start date”): the record already says it.
Leave the owner’s initials, dates and “NEW” out.

Groups

One group per team or purpose, named for what the fields are about, such as “Finance”, “Onboarding”, “Qualification”.
Group names appear only in property settings; the groups on a record sidebar are set up separately (HubSpot guide).
Fewer, broader groups age better than one group per project.

Descriptions

Write one sentence on who fills it in and when, for example “Set by the account manager at handover.” HubSpot’s Documentation tab holds the context and how a user should fill in values.

Put it in a CSV and create everything at once

If you are creating many properties, write the convention into a spreadsheet: one row per property with object, internal name, label, type, group and dropdown options. Then run the file through the free HubSpot property CSV checker, which flags bad internal names, wrong type and field type pairs and broken option lists in your browser; nothing is uploaded. HubSpot has no built-in button that creates properties from a file, so see how to bulk create properties from a CSV for the options.

Keep the convention alive

Write the rules on one page, limit who has the Edit property settings permission, and export all properties once a quarter (HubSpot guide) to compare against the last export.

Full disclosure: our app

Bulk Property Import & Export creates properties, groups and dropdown options from a CSV or a public Google Sheet, with a preview of everything before anything is written. It exports the account’s current setup in the same columns, which is handy for checking a convention against what exists. It cannot rename an internal name, because HubSpot does not allow that, and it reads no CRM records. Import, export and preview are free; Pro is USD 19 per month per HubSpot account, with a 14-day trial and no card. Marketplace listing.

FAQ

Can I rename a HubSpot property’s internal name? No. HubSpot says you cannot edit a property’s object type or internal name. Create a new property and move the values.

Can I change a property label later? Yes, in the property’s settings. Internal names stay the same, so reports and workflows keep working.

Is there a naming convention HubSpot recommends? We did not find an official one in HubSpot’s knowledge base; the template above is ours.

Can I move a property to a different group? Yes. Hover over it, click More, then Move to group.

Questions or corrections: support@kayabyte.dev. HubSpot is a registered trademark of HubSpot, Inc. Kayabyte is an independent developer and is not affiliated with HubSpot.