Hubspot Multi Object Migration Framework

Required Inputs

• Source/target object maps with property-to-property mappings
• Dedupe keys per object type (e.g., email for contacts, domain for companies)
• Migration window: start time, max duration, rollback deadline

Output Artifacts

• Migration execution plan with stage gates and owners
• Checkpointed runbook with rollback instructions per stage
• Reconciliation report: record counts, association counts, error log

Workflow

1. Define scope and success criteria — document source object types, target object types, record volumes, and the definition of "migration complete" (e.g., 100% of source contacts associated to a company in the target schema).
2. Run schema validation gate — query GET /crm/v3/properties/{objectType} for all target types. Confirm every source field maps to an existing target property with a compatible type.
3. Capture baseline evidence — export source record counts and a sample of 50 records per object type. Store in migrations/<run-id>/baseline/.
4. Execute dedupe preflight — identify duplicate dedupe key values in source data. Block migration start if duplicate rate exceeds 5% without a resolution plan.
5. Staged import with HubSpot Imports V3 — use hs-import-advanced --type=multi-file for the 10% sample batch. Inspect error rows via GET /crm/v3/imports/{importId}/errors.
6. Promote to full run — if sample error rate is below threshold, proceed with full import. Run stages sequentially; checkpoint after each object type completes.
7. Reconciliation and sign-off — compare source vs target record counts. Verify association links. Produce the reconciliation report and obtain owner sign-off before decommissioning the source.

Safety Checks

• Enforce staged cutover — never migrate all objects simultaneously; sequence by dependency order (Companies before Contacts before Deals)
• Require rollback checkpoints — export pre-migration state before each stage; keep exports for 30 days
• Validate referential integrity before promotion — no deal should be promoted without its associated contact and company already migrated