Skip to content
Book a build

What naming conventions should HubSpot property internal names follow?

Good HubSpot property naming conventions separate the label people see from the internal name integrations use. Internal names can't be edited after a property is created, so set a rule first: lowercase words joined by underscores, an optional team or source prefix, no dates or people's names. Keep labels plain English, put each property in a named group, and document its purpose.

On this page

What HubSpot supports natively

HubSpot gives each property two names and a few places to explain it:

PartEditable later?Who sees it
LabelYesUsers, on records, forms and filters
Internal nameNo, fixed at creationImports, workflows, integrations and the API (e.g. favorite_food)
Object typeNo
GroupYes, move between groupsProperty settings
Description / documentationYesUsers and admins
Option labels and valuesLabels and options can be editedImports and workflows match on values

HubSpot doesn’t enforce a naming convention for custom properties. Its own properties often start with hs_, which is why that prefix shouldn’t be reused.

A HubSpot property naming convention that holds up

Internal names

  • Lowercase words joined by underscores: renewal_date, contract_value.
  • Optional short prefix for ownership or source when many teams create fields: cs_health_score, erp_customer_number. Pick prefixes once and list them.
  • Describe the data, not the campaign: lead_source_detail, not q3_webinar_field.
  • No dates, people’s names, version numbers or “new” and “old”.
  • Same meaning, same name on every object and every portal. If deals and companies both need contract_value, use the same internal name on both.

Labels

  • Plain English, sentence case, no internal jargon: Renewal date, Contract value.
  • Add the unit where it matters: Annual contract value (USD).

Option values

  • Lowercase with underscores (closed_won_partner), never changed once in use. Change the label instead.

Groups and documentation

  • One group per team or process, such as Customer success or Billing.
  • Fill in the description with what the property means, who maintains it and which system writes to it.

How to apply the convention to an existing portal

  1. Export all properties and sort by internal name to see the patterns already in use.
  2. Write the convention on one page and agree who may create properties.
  3. Apply it to new properties only. Renaming labels is cheap; renaming internal names means creating a replacement.
  4. Fix the worst offenders (duplicates and misleading names) during your next property cleanup.

Where Jetstack AI fits

Jetstack AI’s Portal Audit checks property naming patterns for consistency, along with unused properties and how properties are grouped. When you reuse a setup across clients, Portal reuse keeps the source internal names (unless the destination already has that name with a different type), so every portal gets the same names; you can deploy the same setup to multiple destination portals, reviewing each portal’s mappings. See the Property Management data points. When you build new properties, Projects (currently in limited release) uses the exact internal names and option values you give it in the brief, so the convention holds from the first deployment.

Sources

Checked October 29, 2026. HubSpot changes its products often; tell us at team@jetstack.ai if something here is out of date.

HubSpot admin

See what needs work before you change it.

A read-only Portal Audit and Workflow Audit score the portal, trace dependencies and turn findings into a branded report.

Explore Portal Audit

HubSpot admin

Related questions.

What naming conventions should HubSpot property internal names follow?

Good HubSpot property naming conventions separate the label people see from the internal name integrations use. Internal names can't be edited after a property is created, so set a rule first: lowercase words joined by underscores, an optional team or source prefix, no dates or people's names. Keep labels plain English, put each property in a named group, and document its purpose.

Can I rename a HubSpot property's internal name?

No. HubSpot lets you change the label but not the internal name or the object type after creation. To fix an internal name, create a new property, move the values and update everything that used the old one.

Should I prefix every custom property?

A short prefix helps when several teams or integrations create properties, because you can see who owns what in an export. Don't use hs_, which HubSpot uses for its own properties.

Do option values need a naming convention too?

Yes. Imports and workflows match dropdown options on their internal values, so keep them stable and consistent, for example lowercase with underscores.