---
title: "HubSpot property naming conventions and internal names"
description: "HubSpot property naming conventions that hold up: labels vs internal names, what can't change after creation, a prefix scheme, groups and option values."
url: "https://jetstack.ai/answers/hubspot-property-naming-conventions/"
---

# 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.

![](https://jetstack.ai/images/authors/aditya-kumar.webp)

By [Aditya Kumar](https://jetstack.ai/authors/aditya-kumar/) Founder, Jetstack AI

Updated October 29, 2026

On this page

## What HubSpot supports natively

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

| Part                            | Editable later?                  | Who sees it                                                         |
| ------------------------------- | -------------------------------- | ------------------------------------------------------------------- |
| **Label**                       | Yes                              | Users, on records, forms and filters                                |
| **Internal name**               | No, fixed at creation            | Imports, workflows, integrations and the API (e.g. `favorite_food`) |
| **Object type**                 | No                               |                                                                     |
| **Group**                       | Yes, move between groups         | Property settings                                                   |
| **Description / documentation** | Yes                              | Users and admins                                                    |
| **Option labels and values**    | Labels and options can be edited | Imports 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](https://jetstack.ai/answers/change-hubspot-property-internal-name).
4. **Fix the worst offenders** (duplicates and misleading names) during your next [property cleanup](https://jetstack.ai/answers/delete-unused-hubspot-properties).

## Where Jetstack AI fits

Jetstack AI’s [Portal Audit](https://jetstack.ai/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](https://jetstack.ai/docs/audits/data-points/general). When you build new properties, [Projects](https://jetstack.ai/build) (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

- [Create and edit properties (HubSpot Knowledge Base)](https://knowledge.hubspot.com/properties/create-and-edit-properties)
- [Properties API guide (HubSpot developer docs)](https://developers.hubspot.com/docs/guides/api/crm/properties)
- [Portal Audit: General data points (Jetstack AI documentation)](https://jetstack.ai/docs/audits/data-points/general)

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

![Aditya Kumar](https://jetstack.ai/images/authors/aditya-kumar.webp)

About the author

[Aditya Kumar](https://jetstack.ai/authors/aditya-kumar/)

Founder, Jetstack AI

Aditya Kumar is the founder of Jetstack AI, the AI platform HubSpot partners and RevOps teams use to audit portals, build implementations and reuse their best setups across portals. He writes about HubSpot architecture, automation and AI from the work of building it.

[More from Aditya](https://jetstack.ai/authors/aditya-kumar/) [LinkedIn](https://www.linkedin.com/in/aditya-ambrstack/)

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](https://jetstack.ai/audit)

On this page

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.
