SoCo Circle HubSpot to HubSpot Migration

1. Purpose

This SOP describes how RevGravy migrates CRM data from one HubSpot portal to another using Make.com as the orchestration layer. It covers the four primary CRM objects — contacts, companies, deals, and engagements (notes, calls, tasks, emails) — and the associations that connect them.

The procedure is generic by design. It works for full-portal migrations (everything moves) and for filtered migrations where only a subset of records is in scope. The worked example throughout this document is the SoCo Circle migration, where only deals related to the South office (and the contacts, companies, and engagements connected to those deals) need to move.

The core challenge in any portal-to-portal migration is preserving relationships. Records are easy to copy. What breaks migrations is losing the link between a deal and its contacts, an email and the contact it was logged against, or a company and its child companies. The procedure below addresses this by migrating in dependency order and using a temporary ID-mapping layer in Make.com to translate source IDs into newly created target IDs.

Why this exists HubSpot does not provide a one-click portal-to-portal migration tool that preserves engagements, associations, and custom property values. Make.com gives RevGravy full control of the migration logic, including scoped filters and field-level transformations, but it requires a disciplined process. This SOP is that process. Following it cuts a multi-week project into a predictable 6–8 day execution.

2. Roles & Responsibilities

Role	Responsibility in this workflow
Migration Lead	Owns end-to-end execution. Approves go/no-go at each phase gate. Single point of contact with the client.
Make.com Builder	Builds and tests scenarios, monitors live runs, resolves errors. Owns the Make.com folder for the project.
HubSpot Admin (source)	Generates Private App token. Provides property exports. Coordinates source freeze during cutover.
HubSpot Admin (target)	Recreates schema in target portal — properties, pipelines, owners. Disables workflows for the migration window. Re-enables them post-cutover.
Validator	Independent of the Builder. Runs reconciliation reports, performs spot-checks, signs off on data integrity before cutover.
Client Stakeholder	Confirms scope decisions. Approves cutover. Communicates the change to end users.

 

SoCo Circle example Migration Lead: Manuel. Builder: Manuel + assigned architect. Source HubSpot Admin: client-side IT lead. Target HubSpot Admin: client RevOps manager. Validator: rotating SA (Sparsh, Juan, or Alex — whoever is not building). Client Stakeholder: SoCo Circle VP of Sales (owns the South office decision-making).

3. End-to-End Flow

This is the high-level sequence. Each step is detailed in Section 4.

• Discovery — count records, inventory schema, identify integrations, decide on scope filter.
• Target preparation — recreate properties, pipelines, owners; disable workflows; verify with manual test writes.
• Decisions captured — blank-filter values, engagement scope rule, timestamp preservation, integration handling, cutover model. All documented before build.
• Make.com build — connections, mapping Data Stores, scenarios for each object type, all tested with a single record before scaling.
• Dry run — 50–100 records of each type end-to-end; reconciliation; rollback rehearsal.
• Full run — deals first, then companies, contacts, associations, engagements. Monitored live.
• Validation — independent reconciliation, spot-checks, client UAT.
• Cutover — final delta, workflows re-enabled, integrations re-pointed, source frozen.
• Stabilize — monitor for 30 days, archive Make.com folder, retrospective.

4. Step-by-Step Procedure

Step 1 — Discovery

Trigger: Migration project kicks off. Source and target portals are identified.

Owner: Migration Lead + Builder

Estimated duration: 0.5–1 day

Goal: understand the volume and structure of in-scope data on the source portal. Without this, every later phase is guesswork.

Process

• Generate HubSpot Private App tokens on both portals. Source needs read scopes; target needs read + write scopes. Store tokens in 1Password.
• Export every property definition from the source for each object type (Contacts, Companies, Deals). HubSpot exports this as CSV from Settings > Properties > Export.
• Pull record counts for the in-scope set on the source. If the migration is filtered, run the filter query at this stage to know exactly how much you're moving.
• Pull association counts: how many deal-contact, deal-company, contact-company links exist within the in-scope set.
• Pull engagement counts: notes, calls, tasks, emails associated with in-scope records.
• Inventory pipelines, deal stages, owners, and lifecycle stages used by the in-scope records. These all need to be recreated on the target.
• Identify integrations writing to the source portal — Aircall, SalesMsg, Facebook Ads, calendar tools, etc. Each one's status post-migration must be decided (re-point, pause, or skip).

SoCo Circle example The filter is the deal property Office (internal name office, enumeration with values North and South). Filter applied: office = "South". Discovery findings: Office property has 50.11% fill rate — about half of source deals are blank. This becomes a decision to resolve in Step 3. Source has 403 contact properties and 665 deal properties. After filtering out read-only and calculated fields, ~138 contact and ~222 deal properties need to be migrated 1:1. Active integrations: Aircall, SalesMsg, Facebook Ads, simpleevents.io. All decided to be reconnected on target rather than migrated as data. Custom property groups (site_surveys, inspection, installation_scheduled, pto_&_monitoring) reflect a solar installation business — these are critical and need careful field mapping review with the client.

Output: Field mapping workbook populated with source data; counts logged; integration disposition list; pipeline/owner inventory ready for Step 2.

Step 2 — Target Portal Preparation

Owner: HubSpot Admin (target) + Builder

Estimated duration: 1–2 days

Goal: target portal is ready to receive records. Schema, pipelines, owners, and workflow state are all set. Skipping or rushing this step is the most common cause of migration disasters.

Process

• Recreate properties. Every property marked MIGRATE in the field mapping workbook must exist on the target with the exact same internal name, type, and (for enumerations) the same option list. Internal name match is non-negotiable — the migration scenarios reference these names directly.
• Add timestamp preservation properties. HubSpot's API rejects writes to createdate. If the client wants original creation dates preserved, create source_created_date (datetime) on contacts, companies, and deals.
• Recreate pipelines and stages. Pipeline and stage internal IDs are different across portals even when stage names look identical. Build them on the target, then capture the new IDs in the Pipeline mapping tab of the field mapping workbook.
• Provision users. Every owner whose records are in scope needs a corresponding user on the target. Capture target owner IDs in the Owner mapping tab.
• Disable all target workflows. Take a screenshot of the workflow list before disabling. This is your audit trail for re-enabling correctly later.
• Disable non-essential integrations on the target. Anything that writes to records (HubSpot Insights, marketing tools, sequences) should be paused for the migration window.
• Manual test writes. Create one test record of each type via the HubSpot UI to confirm permissions. Then create one of each via the API using the target Private App token. Both must succeed before moving on.

Critical rule Verify workflows are off before any record is migrated. Migrated contacts will trigger workflow enrollment criteria — sending real emails to real contacts, creating tasks, changing lifecycle stages. The Phase 2 screenshot is your evidence that this happened correctly.

Output: Target portal schema mirrors source. Pipeline mapping and Owner mapping tabs fully populated. Workflows verified disabled. Manual + API test writes succeed.

Step 3 — Decisions Captured

Owner: Migration Lead + Client Stakeholder

Estimated duration: 1–2 hours, asynchronously

Goal: every scope decision is answered in writing before any scenario is built. Decisions made later get expensive.

Decisions to capture

• Filter scope edge cases. If the migration is filtered, what about records where the filter property is blank? In or out?
• Engagement scope rule. Strict (only engagements directly tied to in-scope deals) vs Inclusive (any engagement on any in-scope contact, company, or deal). Default: Inclusive — preserves activity history.
• Original creation timestamps. Preserve to source_created_date custom property? Default: yes, on all object types.
• Engagement timestamps. hs_timestamp IS settable on engagements via the API, so activity history is preserved by default. Confirm this is desired.
• Integration-managed properties. Default: skip; reconnect integrations on target rather than migrating their data, which would be a stale snapshot.
• Cutover model. Big-bang (one weekend, source frozen) vs delta (initial load + incremental sync). Default: big-bang for typical RevOps volumes (under ~250k records).
• Source portal post-cutover. Read-only archive for how long? Default: 30–90 days minimum.

SoCo Circle example Decisions captured: Blank-Office deals: out of scope. Client confirmed these are pre-segmentation legacy records that should not move. Engagement scope: Inclusive. Architects need full activity history for retained South-office accounts. Original creation dates: preserved to source_created_date on all four object types. Integrations: Aircall, SalesMsg, Facebook Ads — all reconnected on target post-cutover, not migrated as field data. Cutover: big-bang over a weekend. Source frozen Friday 6pm ET, target live Monday 8am ET.

Output: Decisions document signed by Migration Lead and Client Stakeholder. Stored in project folder.

Step 4 — Make.com Build

Owner: Builder

Estimated duration: 3–4 days

Goal: every migration scenario exists in Make.com and passes a single-record end-to-end test.

Foundation setup

• Create a Make.com folder named after the migration project. All scenarios live here.
• Create two HubSpot connections: source (read) and target (read + write). Test each.
• Create four mapping Data Stores: deals_map, companies_map, contacts_map, engagements_map. Each has fields source_id (text, primary key) and target_id (text). These translate source HubSpot IDs to the new target IDs created during migration.
• Create two reference Data Stores: owner_map and pipeline_stage_map. Seed them from the Owner mapping and Pipeline mapping tabs of the field mapping workbook.
• Create a Google Sheet with three tabs: Run Log, Error Log, Reconciliation. Connect it to Make.com.

Scenario build order

Build in dependency order. For filtered migrations, the order changes — see the SoCo Circle callout below.

• Companies → Contacts → Deals → Associations → Engagements (notes, calls, tasks, emails). This is the standard order for full-portal migrations.

The 7-module pattern

Every object scenario follows the same pattern. Build it once, copy it for each object type, swap the HubSpot module configuration.

• Module 1 — Search Objects (source). Pull source records. Apply filter at this module if the migration is scoped. Set limit to 100 (HubSpot's max). Sort by createdate ascending so re-runs are deterministic.
• Module 2 — Iterator. Only if needed; HubSpot Make modules typically auto-iterate.
• Module 3 — Data Store: Get. Look up source ID in the mapping store. If a target_id exists, the record was already migrated — skip on re-run.
• Module 4 — Router or Filter. Branch: 'already migrated' vs 'new'.
• Module 5 — HubSpot: Create or Update (target). Create the record. Use upsert variant where available (e.g., contacts upsert by email) for idempotency.
• Module 6 — Data Store: Add or Replace. Write source_id → target_id to the mapping store. Most important step — without this, associations break later.
• Module 7 — Google Sheet log. Append source_id, target_id, status, timestamp to the Run Log. Invaluable for audit and post-migration debugging.

SoCo Circle example — filtered migration changes the order When the filter property only exists on one object (Office is on deals, not contacts or companies), the build order flips. You can't filter contacts directly — there's nothing to filter on. So the in-scope set is determined by deals first, and everything else is derived. SoCo Circle build order: Deals (filter at Search module: office EQ "South") Companies — derived: iterate deals_map → for each source deal, get associated company → dedupe (a company with five South deals only gets created once) → migrate Contacts — derived: iterate deals_map → get associated contacts → dedupe → migrate Associations — translate IDs via mapping stores → create deal-contact, deal-company, contact-company links Engagements — for each in-scope contact/company/deal, fetch engagements (Inclusive rule) → preserve hs_timestamp → migrate → associate via mapping stores

Test discipline

Each scenario MUST pass a single-record test before scaling. The cost of finding a bug at record 1 vs record 30,000 is enormous. Build → test with limit=1 → fix → retest → only then scale.

Output: All scenarios built. Single-record tests pass for each. Mapping Data Stores contain test entries from each scenario.

Step 5 — Dry Run

Owner: Builder + Validator

Estimated duration: 0.5 day

Goal: validate the full pipeline at small scale before committing the full run.

Process

• Set the Search Objects limit to 50 in the leading scenario (Companies for full-portal, Deals for filtered).
• Run the leading scenario, then run downstream scenarios in order. Monitor ops consumption and runtime — extrapolate to full volume.
• Run a reconciliation: counts on source vs target for each object type within the test set.
• Spot-check 10 records of each type. Open in source UI and target UI side by side. Compare every property, owner, stage, association.
• Spot-check 5 contacts' engagement timelines. Confirm note/call/task/email history reproduced with correct timestamps.
• Test the rollback procedure (Section 6). Delete the test records via the cleanup scenario. Verify the target is clean and mapping stores are cleared.
• Document any defects. Fix in scenarios. Re-run the dry run if changes were material.

Go / no-go gate Migration Lead must approve the dry run results in writing before Step 6 (Full Run). Any unresolved defect — even a small one — is a blocker. The full run will amplify, not absorb, problems.

Output: Dry run report with reconciliation counts, defect log, and Migration Lead sign-off.

Step 6 — Full Migration Run

Owner: Builder, with Validator on standby

Estimated duration: 1–3 days depending on volume. Email engagements typically dominate.

Goal: complete the full data move within the cutover window.

Process

• Communicate the start of the migration window to client and end users. Source portal is now considered frozen — any user-side changes during this window will not be migrated.
• Re-confirm target workflows are still disabled and integrations are still in their planned state. A second screenshot for the audit trail.
• Run scenarios in dependency order. Validate after each before proceeding. Reconciliation: source count = target count = mapping store row count. All three numbers must match.
• Engagement scenarios are the longest. Notes, calls, tasks first (smaller volumes); then emails last. Email engagements often dominate total volume — split by date range across multiple scenarios for parallel execution if needed.
• Review the Error Log after each scenario. Disposition each unique error: ignore (one-off bad data), fix and retry (scenario bug), or escalate (systemic issue).

Live monitoring

• Watch the Make.com ops dashboard hourly during long-running scenarios. Hitting the ops cap pauses everything.
• Watch the target portal's HubSpot API usage. If approaching daily cap, pause and resume the next day.
• Watch the Run Log Google Sheet — it should be growing at a steady rate. Sudden stalls usually indicate a 429 backoff cycle or a hung module.
• If a scenario crashes mid-run, the mapping-store check at module 3 of the standard pattern means it's safe to restart. Pick up where it left off using the last source record's lastmodifieddate.

SoCo Circle example Low end (30 engagements/deal): ~265K ops including buffer Midpoint (40): ~340K ops including buffer High end (50): ~415K ops including buffer

Output: All in-scope records on target. Mapping stores complete. Error Log dispositioned.

Step 7 — Validation

Owner: Validator + Client Stakeholder

Estimated duration: 0.5–1 day

Goal: independent verification that the migration is correct and complete before users start working in the target. This step exists because the Builder is too close to the work to spot their own gaps.

Reconciliation reports

• Counts. Source in-scope vs target migrated, by object type. Discrepancies must be investigated and explained.
• Pipeline value. Total deal amount per stage, source vs target. Variance > 1% triggers investigation.
• Owner distribution. Deal/contact count per owner, source vs target. Confirms owner mapping is correct.

Spot-checks

• 25 random deals end-to-end. Use a true random sample, not a curated one — curated samples mask issues that random samples reveal.
• 25 random contacts including engagement timelines.
• Phantom-record check. Any target record without a matching entry in its mapping store is a leak. Investigate each.

Client UAT

• Provide the client with target portal access. Have a sales user open 5 deals they recognize and confirm they look right. This is the gut-check step — does it feel right to someone who knows the data.

Critical rule Validator and Client Stakeholder both sign off in writing. No cutover happens without both signatures.

Output: Validation report. Client UAT sign-off. Migration Lead approval to proceed to cutover.

Step 8 — Cutover

Owner: Migration Lead

Estimated duration: 0.5 day

Goal: transition users from source to target cleanly.

Process

• Final delta check. Any records modified in source between freeze and now? Run a one-shot delta scenario if so.
• Re-enable target workflows. Compare to the Step 2 screenshot to confirm none were accidentally enabled, added, or modified during the migration window.
• Re-point integrations to target. One at a time. Test each. 
• Lock the source portal. Revoke user write permissions or set the entire portal to read-only via user role changes.
• Send go-live announcement. To all users with: target portal URL, what changed, where to get help, when source will be archived.
• Stand by for the first 4 business hours after go-live. Triage incoming questions in real time.

Output: Target is live. Users are working in it. Source is read-only.

Step 9 — Stabilize & Close

Owner: Migration Lead

Estimated duration: 0.5 day spread across 30 days post-cutover

Process

• Day 1. Monitor target for unusual workflow firing, integration errors, or user-reported issues.
• Day 7. Fresh count from target. Confirm growth pattern is normal (new records being created, not bulk imports leaking).
• Day 30. Archive the Make.com folder (do not delete). Export Data Stores to CSV and store in project folder. The mapping data is the audit trail.
• Day 30. Hold a retrospective. Document what went well, what didn't, what to change for the next migration.
• Day 30+. Client decides whether to delete source portal data or retain longer. Default retention: 90 days minimum.

Output: Project archived. Retrospective document. Source portal disposition decision logged.

5. Troubleshooting

Problem	Likely cause	Resolution
HTTP 429 rate limit	Too many requests in 10s window	Increase Sleep module to 500ms+. Set scenario sequential processing to Yes. Break + Retry handler should already absorb most.
HTTP 400 invalid property	Property doesn't exist on target, or internal name typo	Check target Settings > Properties. Recreate property with exact internal name match. Internal name case-sensitive.
HTTP 400 invalid enumeration value	Source value not in target's option list	Add missing option to target property, or transform the value in the Make.com module.
Deal lands in wrong pipeline stage	Pipeline mapping incomplete or stage IDs wrong	Verify Pipeline mapping tab against the target portal. Stage IDs differ across portals even when names match.
Records have no owner	Source owner not in owner_map, or owner was deleted	Add the owner to mapping. If owner was deleted, decide on fallback (often a 'Migration' service user).
Duplicate contact created	Two source contacts share an email	Upsert by email handles this — second one updates first. Confirm desired; if not, dedupe at source first.
Engagement timeline empty on target	Associations not built, or hs_timestamp not preserved	Verify engagement scenario writes hs_timestamp. Verify Associations scenario ran and mapping store has entries.
Make.com ops exhausted mid-run	Plan limit hit	Purchase ops add-on or upgrade plan. Resume scenarios — mapping stores ensure idempotent restart.
HubSpot daily API cap hit	High call volume on lower-tier portal	Pause until cap resets. Confirm target tier supports the planned volume before next migration.
Workflow fired during migration	Workflows not properly disabled	Pause migration. Disable workflows. Assess damage (emails sent, lifecycle changes). May need partial rollback.

 

6. Rollback Procedure

If a critical issue is discovered during or after the full run that cannot be fixed forward, follow this procedure. Rollback is faster the earlier you call it.

During the run (mid-execution)

• Pause the running scenario in Make.com.
• Identify the failure mode. Most common: misconfigured mapping, integration writing to target during run, hit rate limit.
• If recoverable: fix the scenario, restart. Mapping stores ensure idempotency — already-migrated records get skipped.
• If not recoverable: proceed to full rollback.

Full rollback

• Confirm with Migration Lead and Client Stakeholder that rollback is the chosen path. Document the trigger reason.
• Stop all running Make.com scenarios.
• Run the rollback cleanup scenario: iterate each mapping store and issue a delete call to the target HubSpot for each target_id.
• Verify target counts return to the pre-migration state.
• Clear the mapping Data Stores.
• Source portal remains untouched; users continue working in it.
• Triage. Fix. Plan a re-run.

Rollback only deletes what you migrated The cleanup scenario uses the mapping stores as its source of truth. It only deletes records the migration created. Records created on target by other means (manual entry during the migration window, or other integrations not properly disabled) are NOT touched. This is by design — but it's also why disabling integrations and workflows in Step 2 matters.

6. Future State — Tooling Improvements

This SOP documents the standard process. The following improvements are scoped for future cycles and would reduce execution time or risk on subsequent migrations.