> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate from HubSpot to Orbit: reconnect, or run both

> Move your marketing automation, contact book, and lifecycle stages off HubSpot (or alongside it) — the bidirectional loop, the list-to-segment map, and the seven-step relink runbook.

# Migrate from HubSpot to Orbit

"Migrate from HubSpot" spans the same split the Salesforce migration does — a CRM is a system of record, not a send pipe. Pick the row that matches what you actually need:

| What you mean                                                             | The move                                                                                                                                                |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Send Orbit campaigns against HubSpot lists as the live source             | Don't migrate — keep HubSpot live, connect it, and point campaigns at the list. [Connect HubSpot & Salesforce](/guides/hubspot-salesforce-integration). |
| Run engagement from Orbit while HubSpot stays your system of record       | Don't migrate — set up the full loop: inbound sync, outbound write-back, timeline events. Same guide.                                                   |
| Consolidate: retire HubSpot and run customer engagement entirely in Orbit | **This guide.** The bidirectional loop below still matters — you run it while both are live.                                                            |

The connector is identical either way. What changes is how long it stays, and what you rebuild natively. The sections below are ordered for a consolidation; sections 1–3 are just as useful for a side-by-side setup, since you run them in both cases anyway.

## 1. What's exported from HubSpot — before you change anything

Export from HubSpot while both sides still have full data:

* **Contacts** — a CSV of the portal's contact list, with the properties your segments use (Email, Phone, lifecycle stage, your `hubspot:*` custom properties). Include `hs_lead_status` and your marketing-consent field.
* **Companies** — the account dimension, mapped into the CDP `accounts` entity for [linked audiences](/guides/linked-audiences).
* **Deals** — history, not a daily workflow in Orbit. Your pipeline view is rebuilt natively only if you need to segment on it; otherwise archive.
* **Lists** — static lists export as CSVs directly; active lists export via a filtered view. The distinction matters: a static list is over, an active list moves.
* **Marketing emails and templates** — there is no per-template export; rebuild templates in Orbit per the [email lifecycle guide](/guides/email-lifecycle-guide#3-build-templates).
* **Workflows** — HubSpot workflows do not export. Rebuild each in Orbit as a [flow](/guides/build-first-flow), a [campaign journey](/guides/campaign-journey-builder), or a [journey from prompt](/guides/campaign-journey-from-prompt) starting from a plain-language description of the goal.

Keep the exported CSVs — they are the audit spine if a row doesn't reconcile after the relink.

## 2. Connect HubSpot to Orbit (OAuth, admin-only)

The connection is the Nango OAuth integration. **Owner/admin role required** — it touches provider credentials.

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/integrations/connect \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "integration_id": "hubspot" }'
```

The response returns an `auth_url`; redirect the browser to it and complete the OAuth consent. Inbound sync then runs on two paths — a scheduled poller, and real-time via `POST /api/v1/integrations/webhooks/hubspot` (once you add that URL to your HubSpot App's webhook subscriptions). Both populate the Orbit contact book.

Verify the connection landed:

```bash theme={null}
curl https://api.orbit.devotel.io/api/v1/integrations \
  -H "X-API-Key: dv_live_sk_your_key_here"
# Expect a row for provider: 'hubspot' with connected: true
```

Link fields populate on each contact — email, phone, first/last name, `lifecyclestage`, and your `hubspot:`-namespaced custom attributes. The identifier link is written as `attributes.hubspot_id` on each contact. Orbit also handles the **outbound write-back** automatically — a contact change in Orbit enqueues a `hubspot-contact-push` and the patch only lands in HubSpot if the contact is linked (no link → `not_linked` + audit, never an exception).

## 3. Recreate your audiences in Orbit

A HubSpot list is a live object — moving it means recreating it as a native Orbit segment, or pointing a campaign at the list while HubSpot is still live:

| HubSpot object                                                                                       | Orbit destination                                                                                         | When to use it                                                                                                     |
| ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Active list (a saved filter over contacts)                                                           | [CDP segment](/guides/cdp-segments) over the synced contact book, with the same filter as a live query    | Most common replacement; the HubSpot list retires once the Orbit segment resolves to the same member set.          |
| Static list (a one-off snapshot)                                                                     | [CSV import](/guides/import-contacts) into Orbit, then a tag or segment on those rows                     | Day-zero data consolidation; the HubSpot list is archived.                                                         |
| List you still trust in HubSpot                                                                      | Point the campaign at the live list — audience\_source: `hubspot_list`, `ref`: the list id                | HubSpot remains the source of truth; Orbit resolves members at send time. Works only while the connection is live. |
| A segment that traverses Companies → Deals (e.g. "profiles linked to a company on an open-won Deal") | [Linked audiences](/guides/linked-audiences) — model the entities once, then compose relational audiences | Your targeting is relational, not a flat filter over one object.                                                   |

Rebuild lists before you retire the HubSpot portal — a campaign that points at a HubSpot list works only while the connection is live.

## 4. Mirror ongoing activity back to HubSpot (optional but recommended while both live)

While HubSpot stays live, Orbit writes every new message and call back into the contact's engagement timeline — a HubSpot user opens a Contact and sees Orbit SMS/WhatsApp/voice/email mixed chronologically with the portal's native touches. Fail-open per the [CRM activity logger](/guides/hubspot-salesforce-integration#step-5---failure-modes-and-monitoring) design — a HubSpot outage never blocks an Orbit send.

The provider mapping is:

| Orbit channel        | HubSpot engagement                                                |
| -------------------- | ----------------------------------------------------------------- |
| SMS / MMS / WhatsApp | Communication (`hs_communication_channel_type: SMS \| WHATS_APP`) |
| RCS                  | Communication (mapped to SMS)                                     |
| Voice                | Call engagement                                                   |
| Email                | Email engagement                                                  |

Enable when the two run side-by-side; skip it if you're cutting HubSpot inside a month.

## 5. Rebuild the daily workflow in Orbit

HubSpot's marketing, sales, and service surfaces map to Orbit's own products:

| HubSpot surface                     | Orbit equivalent                                                                 |
| ----------------------------------- | -------------------------------------------------------------------------------- |
| Marketing Hub campaigns / sequences | [Campaigns](/guides/campaign-end-to-end) with multi-channel steps                |
| Sales Hub sequences                 | [Campaign journeys](/guides/campaign-journey-builder)                            |
| Service Hub inbox                   | [Unified inbox](/guides/inbox-setup) — SMS, WhatsApp, email, voice in one thread |
| Service Hub tickets                 | [Inbox tickets](/guides/inbox-tickets-workflow)                                  |
| Marketing email + templates         | [Email channel](/guides/smtp-send-email)                                         |
| Chatflows / Conversations           | [AI agents](/guides/agent-studio-canvas)                                         |
| Workflows                           | [Flows](/guides/build-first-flow)                                                |
| Reports                             | [Analytics](/guides/ask-your-data-insights)                                      |

Rebuild gradually — leave HubSpot live while you move one workflow over at a time and harden it. The [seven-step cutover runbook](/guides/migration-playbook-hub#4-runbook-for-cutover--the-canonical-seven-steps) applies unchanged; the only HubSpot-specific detail is which lists step 3 and which write-back flag step 6 close out.

## 6. Reconcile, then cut over

The generic seven-step cutover in [Migration playbook hub](/guides/migration-playbook-hub#4-runbook-for-cutover--the-canonical-seven-steps) works as-is; these are the HubSpot-specific checkpoints to hang off it:

1. **Freeze sends in HubSpot** — Marketing Hub campaigns, Sales sequences, form-triggered automation; whatever sends. Verify the HubSpot portal's active sends read empty while Orbit keeps flowing on the split.
2. **Redirect webhooks** — verify `POST /api/v1/integrations/webhooks/hubspot` against your HubSpot App's signature verification (`X-HubSpot-Signature-v3`); if your own receiver mirrors Orbit events, replay a `message.delivered` against the `X-Orbit-Signature` HMAC.
3. **Swap API keys** — cut your own integration (if any) onto an Orbit key; the OAuth connection to HubSpot itself stays until decommission.
4. **Flip sender identity** — the production sender moves to Orbit's numbers; email sender verification moves to Orbit's domain auth.
5. **Watch the first-hour parity window** — delivery-rate parity on the split class before decommission.
6. **Hold the fallback warm** — keep the portal connected for one billing cycle if needed; the connector revokes independently from closing the portal.
7. **Decommission** — verify no live sends in HubSpot, no webhook subscriptions pointing at Orbit you still need, and your exported CSVs reconcile with what Orbit reports imported. Then close the portal.

## 7. Operate after the migration

Once cut over, the ongoing surfaces that keep the migration honest:

* **Settings → Migrations** — the job history for every import run lives here, with status and rollback. [Monitor, cancel, and roll back platform migrations](/guides/migration-jobs-operations).
* **Audit ledger** — every relink, write-back push, rollback, and webhook receipt lands in the audit log; the success and failure markers are `crm.contact.pushed_to_hubspot` and `crm.contact.push_failed_hubspot`.
* **Suppression and consent state** — HubSpot subscription types and unsubscribe lists must exist in Orbit's per-channel suppression before decommission. [Opt-out lists](/guides/opt-out-lists) covers how Orbit enforces it.
* **Sync health** — if you left HubSpot connected as a record, `GET /api/v1/integrations/{id}/status` reports the per-sync `last_sync` timestamp; **Settings → Integrations → HubSpot → Status** surfaces the same.

<Tip>
  Consolidating off HubSpot entirely, or running both for a season? The solutions team works HubSpot offloads regularly — [migrate@devotel.io](mailto:migrate@devotel.io) with your portal shape and traffic mix gets you the same dual-run plan the sections above assume.
</Tip>