Custom properties are the backbone of a HubSpot portal. They power segmentation, reporting, workflows and integrations. They are also the first thing to turn into a mess. Here is a practical approach to keeping them manageable.
1. Ask before you create
Before adding a property, check whether a default or existing one already covers it. Then answer three questions: who will use it, which report or workflow needs it, and who owns its accuracy? If you cannot answer all three, do not create it yet. Also remember that the number of custom properties you can create depends on your HubSpot subscription, so every unnecessary property uses up room you may need later.
2. Use a consistent naming convention
Labels are for people; internal names are for code, and HubSpot does not let you edit a property's internal name or object type after creation, so choose them carefully. In HubSpot the internal name must start with a letter and be lowercase; the safest convention is to use only lowercase letters, numbers and underscores. A simple pattern works well:
- Label: clear, human wording, such as "Contract Renewal Date". Labels can be edited later.
- Internal name: lowercase with underscores, such as
contract_renewal_date. - Prefix by domain where it helps, for example
onb_for onboarding fields.
If you create properties through the API (POST /crm/v3/properties/{objectType}), you supply the name (internal name), label, groupName, type and fieldType yourself, so the same convention should be enforced in your code.
3. Pick the right field type
Prefer dropdowns, checkboxes and date pickers over free text. Structured values keep filters and reports reliable. Use single-line text only when the answer truly is open-ended. Be careful when changing a field type later: it can invalidate the values already stored in the property. For identifiers that must never repeat, such as an ID from an external system, the API lets you set hasUniqueValue to true (up to ten unique-value properties per object).
4. Group and describe
Put every property in a meaningful property group and fill in the description. Groups keep the property settings organised and make it easier to see where data comes from, which is especially useful for properties created by integrations. Write the description so that it explains what the field means, when to fill it and who updates it.
5. Govern over time
- Review properties quarterly and archive unused ones. Archived properties can be restored for 90 days, after which they are permanently deleted. A property that is still used in a workflow, segment, form, property card or similar tool cannot be archived until you remove it from there.
- Restrict edit permissions on critical fields. Creating and changing properties requires the "Edit property settings" permission, so give it to as few people as possible.
- Document sources: manual entry, workflow, form or integration.
- Use required fields on forms sparingly to protect conversion rates.
Conclusion
A tidy property schema saves hours of cleanup later. Plan before you create, name consistently, choose structured types and review regularly. Your reports will thank you.
