cleanup-forms

name	cleanup-forms
description	Audit and remove unused, test, or deprecated forms from HubSpot. Identifies forms with zero submissions, forms not embedded on any page, and test forms left over from development.
license	MIT
metadata	{"author":"tomgranot","version":"1.1","category":"ongoing-maintenance"}

Cleanup Forms

Audit HubSpot forms to remove unused and test forms. Stale forms clutter the forms dashboard and can cause confusion when building workflows or reports.

Prerequisites

• A HubSpot private app access token (HUBSPOT_ACCESS_TOKEN in .env) with forms scope
• Python 3.10+ with uv
• Note: The Forms API may return 403 on some plan tiers. If so, perform the audit manually in the HubSpot UI under Marketing > Forms.

Step-by-Step Instructions

Stage 1: Plan

Confirm with the user before starting:

1. How aggressive to be: delete outright, or prefix with "[DEPRECATED]" first and delete next quarter?
2. Any forms that must never be touched (compliance, legal, active campaigns)?

Stage 2: Before

Inventory all forms via the Marketing Forms API (v3):

import os, requests
from dotenv import load_dotenv

load_dotenv()
TOKEN = os.environ["HUBSPOT_ACCESS_TOKEN"]
BASE = "https://api.hubapi.com"
HEADERS = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}

forms, after = [], None
while True:
    params = {"limit": 100}
    if after:
        params["after"] = after
    resp = requests.get(f"{BASE}/marketing/v3/forms", headers=HEADERS, params=params)
    resp.raise_for_status()
    data = resp.json()
    forms.extend(data.get("results", []))
    after = data.get("paging", {}).get("next", {}).get("after")
    if not after:
        break

For each form, record: form ID, name, type, submission count, created date, last submission date.

Stage 3: Execute

Flag forms matching any of these criteria:

1. Zero submissions and created more than 30 days ago
2. No recent submissions (last submission 6+ months ago) and not embedded on an active page
3. Test forms (names containing "test", "temp", "draft", "copy of")
4. Deprecated forms replaced by newer versions

Before deleting, check:

• Is the form referenced in any workflow enrollment trigger?
• Is the form embedded on any live landing page or website page?
• Is the form used in any pop-up or slide-in CTA?

Present the candidate list to the user and wait for explicit confirmation, then delete confirmed unused forms via the API (DELETE /marketing/v3/forms/{formId}) or UI.

Stage 4: After

1. Re-run the inventory and confirm the deleted forms are gone.
2. Document what was deleted in a cleanup log.
3. If a form with submissions is deleted, the submission data is retained on the contact records — but the form definition is gone.

Rollback

• Deleted forms cannot be restored in HubSpot.
• Before deleting a form with any submissions, export the form definition (field names, settings) so it can be recreated.
• Contact records retain their form submission history regardless of form deletion.

Tips

• Establish a naming convention: [TEAM] - Purpose - Version (e.g., [Marketing] - Webinar Registration - v2).
• Prefix deprecated forms with "[DEPRECATED]" instead of deleting immediately — delete after one quarter of no usage.