> ## Documentation Index > Fetch the complete documentation index at: https://docs.useorbitcrm.ai/llms.txt > Use this file to discover all available pages before exploring further. # Migrate from HubSpot > Bring your HubSpot contacts, companies, deals, pipelines and history into Orbit with the built-in import. No code or spreadsheets needed. Orbit reads your HubSpot portal directly and brings it over in the background. You can keep working in HubSpot while it runs, and run it again later to pick up anything that changed. > [!NOTE] > > Only owners and admins of your Orbit workspace can start an import. In HubSpot, the person who creates the key in step 2 is easiest as a **super admin**. ## What comes over | HubSpot | Orbit | | - | - | | Contacts (with owner, company, job title, phone, creation date, lifecycle stage, lead status, custom properties) | Contacts, linked to their companies, with their lifecycle stage and lead status in Orbit's own fields. Stages and statuses your portal added are added to Orbit's lists (Settings → Lifecycle) under the same names | | Companies (with creation date) | Companies, matched by domain, with their lifecycle stage. HubSpot companies that share a domain become one Orbit company, with all their contacts, deals and history | | Deal pipelines and stages | Pipelines with the same stages; closed stages at 100% become won stages, other closed stages lost | | Deals (amount, close date, owner, company, contacts, stage history) | Deals in the matching stage, with the stages they went through and when they entered each; won and lost deals keep their close date | | Custom properties | Custom fields, up to 50 per object | | Notes, emails, calls, meetings, tasks | The record's timeline, with the original time and author | | Files attached to notes, emails, calls, meetings and tasks | Files on the same records and notes, when the key has the optional file scopes | | Association labels ("Decision maker") | The same labels on Orbit's contact–company and deal links | | Opted-out and bounced contacts | The unsubscribe list, so nobody is emailed by mistake | Every record keeps its HubSpot id, so running the import again updates records instead of duplicating them. Dates come over as HubSpot has them: when each record was created, when deals closed and entered their stages, when tasks were completed, and when every note, email, call and meeting happened. Close dates are the days HubSpot shows in your portal's time zone. A contact or company Orbit already had (say, a lead from one of your forms) takes HubSpot's creation date when HubSpot's is earlier. Stage changes HubSpot recorded show on the deal as **Imported from HubSpot**, at the time they happened there. They count toward time in stage and the sales reports like changes made in Orbit. Not imported: files in HubSpot's file manager that aren't attached to a note, email, call, meeting or task, and marketing assets such as email templates, sequences and workflows. > [!NOTE] > > Imported before lifecycle stages came to Orbit? Those imports kept HubSpot's lifecycle stage and lead status in two custom fields, **HubSpot lifecycle stage** and **HubSpot lead status**. Orbit converts those values into the new fields for you: contacts that already have a stage or status set in Orbit keep it, and no contact's qualification changes. You don't need to import again. Once the new fields are filled, you can delete the two custom fields from **Settings → Contacts → Fields**. ## Steps **1. Invite your team to Orbit** Records keep their HubSpot owner when that person is an Orbit member with the same email address. Invite everyone who owns records in HubSpot from **Settings → Members** before you import. **2. Create a service key in HubSpot** Orbit reads HubSpot with a **service key**, a read-only key you create for this import. 1. In HubSpot, click the settings gear and go to **Integrations → Service keys**. In some accounts it is under **Development → Keys → Service keys** instead. 2. Click **Create service key** and name it `Orbit import`. 3. Click **Add new scope**, type each scope below into **Find a scope** and tick it, then click **Update**. 4. Click **Create** and confirm. ``` crm.objects.contacts.read crm.objects.companies.read crm.objects.deals.read crm.objects.owners.read crm.schemas.contacts.read crm.schemas.companies.read crm.schemas.deals.read sales-email-read ``` Every scope is read-only: Orbit never changes anything in HubSpot. `sales-email-read` brings the content of logged emails. To bring over attached files too, also add these two optional scopes. Without them the import runs as usual and says that files were left out. ``` files files.ui_hidden.read ``` > [!NOTE] > > Creating a service key needs a HubSpot **super admin**, or a user with **Developer tools access**. A key can only be given scopes its creator already has, so if a scope can't be ticked, ask a super admin to create the key. > [!TIP] > > Already have a HubSpot private app from before? Its access token works too. HubSpot stopped creating new legacy private apps in October 2026, which is why new imports use service keys. **3. Copy the key** Open the key you just created, click **Show**, then **Copy**. It starts with `pat-`. **4. Start the import in Orbit** In Orbit, go to **Settings → Migrate CRM**, pick **HubSpot**, and click **Start import**. The same import is under **Settings → Integrations → HubSpot**. Paste the key, then choose: * **What to import**: contacts, companies, deals and pipelines, and history (notes, emails, calls, meetings and tasks). * **Do-not-contact list**: contacts who opted out or bounced in HubSpot are unsubscribed in Orbit too. * **Records already in Orbit**: update them with HubSpot's values, or leave them as they are. Click **Start import**. **5. Watch it run** The import runs in the background, so you can leave the page. Come back to **Settings → Migrate CRM** to see its progress: for each object, how many records were read, created, updated, skipped, and how many had errors. Skipped records include ones HubSpot has nothing to import for, such as a contact without an email address (Orbit keeps contacts by email), an empty note, or an email that isn't linked to any contact, company or deal, with their reasons and counts listed under the table, and companies merged into another company with the same domain, which are explained there too. Examples of rows with problems follow. ## After the import * **Check the report** on the import card. For each object it shows how many records HubSpot has, how many were imported, how many were skipped (with the reason, such as a contact without an email address) and how many had problems. If HubSpot reports more than the import read, records were usually added while it ran: **Import again** picks them up. * **Check your pipelines** under **Settings → Pipelines**. They are created from HubSpot's, with the same stage names. * **Webhooks and connected apps** don't receive imported records unless that is turned on under **Settings → Integrations → Connected apps**, so the import doesn't flood your automations. * **The key is deleted from Orbit** when the run completes or is cancelled. You can delete the service key in HubSpot too, and create a new one if you import again later. ## Run it again, resume or cancel * **Run it again** at any time with **Import again**. Records are matched by their HubSpot id, so changes are updated and nothing is duplicated. Choose **Leave them as they are** to only add records that are new since the last run. * **Cancel** a running import from its status card. Records already imported stay. * **Resume** a failed or cancelled run and it picks up from the last page it finished. A failed run keeps the key, so you can resume without pasting it again. A cancelled run has deleted it, so paste the key again. * One import can run per workspace at a time. ## Troubleshooting > [accordion] "HubSpot rejected this key" > > The key was mistyped, deleted, or rotated in HubSpot. Copy it again from **Settings → Integrations → Service keys** (or **Development → Keys → Service keys**; click **Show**, then **Copy**) and paste it into the import, or resume the run with it. > [accordion] "HubSpot refused to share … the credential lacks the scope for it" > > The key is missing one of the scopes above. Open the key in HubSpot, click **Add new scope**, add the missing scope and save. Then resume the run in Orbit: it continues where it stopped. > [accordion] I can't find Service keys, or can't tick a scope > > Service keys are under **Settings → Integrations → Service keys**, or in some accounts **Development → Keys → Service keys**. They need a HubSpot super admin, or a user with Developer tools access. A key can only be given scopes its creator has. Ask a super admin to create the key and send it to you. > [accordion] Only some custom properties came over > > Up to 50 custom properties per object become Orbit custom fields. HubSpot's built-in, hidden and calculated properties are left out. > [accordion] Some contacts were skipped for having no email address > > Orbit keeps one contact per email address, so a HubSpot contact with no email has nothing to import. Notes and emails attached only to such a contact are skipped with it, and a deal attached to one is imported without that contact. Add an email address in HubSpot, then run the import again with **Update them with HubSpot's values**. > [accordion] Records have no owner > > Owners are matched by email. Invite the missing people to your Orbit workspace, then run the import again with **Update them with HubSpot's values**. > [accordion] "Only workspace admins can import from HubSpot" > > Ask an owner or admin of your Orbit workspace to start the import, or to make you an admin under **Settings → Members**. ## Other ways to move over * **Spreadsheets**: on **Settings → Migrate CRM**, pick HubSpot and choose **Prefer spreadsheets?** for export steps, sample sheets and uploads. * **From code**: to transform data on the way, or to bring file attachments across, see [Migrating from HubSpot](https://docs.useorbitcrm.ai/developers/migrating-from-hubspot.md) in the developer docs. * **Help from our team**: for a large or unusual portal, [contact support](https://docs.useorbitcrm.ai/support/contact.md) and we'll help you get it in. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.