Cleanup Properties
Remove or archive unused custom properties. Property bloat slows down forms, confuses users, and makes data mapping harder.
Prerequisites
- - HubSpot API token in INLINECODE0
- Python with
hubspot-api-client installed via INLINECODE2
Step-by-Step Instructions
Stage 1: Before — Inventory All Custom Properties
Pull properties for each object type:
CODEBLOCK0
For each custom property, record: name, label, object type, type, group, number of records with a value (requires search queries), whether it is used in any form/workflow/list.
Stage 2: Execute — Identify Candidates for Deletion
Safe to delete:
- - Properties with zero populated records and not used in any form, workflow, or list
- Properties with names containing "test", "temp", "old", "copyof"
- Properties created by deactivated integrations
Handle with care:
- - Salesforce sync properties (
hs_salesforce_* prefix or mapped in sync settings) — do not delete without coordinating with the Salesforce admin - Form fields — check if the property is used on any active form before deleting
- Workflow dependencies — check if any workflow reads or sets this property
- Calculated properties — check if other calculated properties reference this one
Archive instead of delete when:
- - The property has historical data that might be needed for reporting
- You are unsure whether anything depends on it
Stage 3: After — Delete or Archive
- 1. Archive properties first (HubSpot supports property archiving).
- Wait 30 days, then delete archived properties that caused no issues.
- Document all changes in a cleanup log.
Stage 4: Rollback
- - Archived properties can be unarchived at any time.
- Deleted properties cannot be restored. The property definition and all associated data are permanently lost.
- Always archive before deleting to provide a safety window.
Tips
- - Run this quarterly as part of the database cleanup routine.
- Establish a property naming convention going forward (e.g.,
team_purpose_detail). - Limit who can create custom properties to prevent sprawl.
- HubSpot has a property limit per object type — cleanup prevents hitting it.
清理属性
移除或归档未使用的自定义属性。属性臃肿会拖慢表单速度、让用户感到困惑，并使数据映射更加困难。
前提条件
- - .env 文件中包含 HubSpot API 令牌
- 通过 uv 安装的 hubspot-api-client Python 包
分步操作指南
第一阶段：操作前 — 盘点所有自定义属性
为每种对象类型拉取属性：
python
from hubspot import HubSpot
apiclient = HubSpot(accesstoken=os.getenv(HUBSPOTAPITOKEN))
for obj_type in [contacts, companies, deals]:
props = apiclient.crm.properties.coreapi.get_all(
objecttype=objtype
)
customprops = [p for p in props.results if not p.hubspotdefined]
针对每个自定义属性，记录：名称、标签、对象类型、类型、分组、包含值的记录数量（需执行搜索查询）、是否在任何表单/工作流/列表中使用了该属性。
第二阶段：执行 — 识别可删除的候选属性
可安全删除的：
- - 零条填充记录且未在任何表单、工作流或列表中使用的属性
- 名称包含 test、temp、old、copyof 的属性
- 已停用集成创建的属性
需谨慎处理的：
- - Salesforce 同步属性（hssalesforce* 前缀或已在同步设置中映射）— 未经与 Salesforce 管理员协调，不得删除
- 表单字段 — 删除前需检查该属性是否在任何活跃表单中使用
- 工作流依赖项 — 检查是否有任何工作流读取或设置此属性
- 计算属性 — 检查是否有其他计算属性引用了此属性
应归档而非删除的情况：
- - 该属性包含可能用于报告的历史数据
- 不确定是否有任何内容依赖该属性
第三阶段：操作后 — 删除或归档
- 1. 首先归档属性（HubSpot 支持属性归档）。
- 等待 30 天，然后删除未引发问题的已归档属性。
- 在清理日志中记录所有更改。
第四阶段：回滚
- - 已归档的属性可随时取消归档。
- 已删除的属性无法恢复。属性定义及所有关联数据将永久丢失。
- 务必先归档再删除，以提供安全缓冲期。
提示
- - 每季度执行一次，作为数据库清理例程的一部分。
- 建立后续的属性命名规范（例如：teampurposedetail）。
- 限制可创建自定义属性的人员，以防止属性泛滥。
- HubSpot 对每种对象类型有属性数量限制 — 清理可避免达到该限制。
