> ## 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. # HubSpot Integration > Sync form leads directly to your CRM ![HubSpot](https://mintcdn.com/orbitai-d647f397/T1yKN7sdBmMTM8cv/_images/integrations/HubSpot.svg?fit=max\&auto=format\&n=T1yKN7sdBmMTM8cv\&q=85\&s=1fdf3aa6d2c9545d9ce8348dfc8ed927) > [!NOTE] > > This integration requires a **Pro** plan. [Visit HubSpot](https://www.hubspot.com) ## Start Here ### Overview Connect your OrbitForms forms to HubSpot CRM and automatically create or update contacts and companies when forms are submitted. Perfect for capturing leads, managing customer inquiries, and powering your marketing automation. > [!NOTE] > > **Why This Matters** > > Manual lead entry is slow and error-prone. With the HubSpot integration, every form submission automatically creates or updates a contact in your CRM, saving your team hours of data entry and ensuring leads never slip through the cracks. ## Key Features > [card] Create Contacts > > Automatically create new contacts from submissions. > [card] Sync Companies > > Create or update company records alongside contacts. > [card] Smart Deduplication > > Update existing records if email matches. > [card] Activity Timeline > > Branded activity notes appear in HubSpot. ## Import from HubSpot Moving your CRM over? Orbit pulls your HubSpot portal itself, in the background, from **Settings → Migrate CRM** (or **Settings → Integrations → HubSpot → Import from HubSpot**). For the full walkthrough, see [Migrate from HubSpot](https://docs.useorbitcrm.ai/guides/migrate-from-hubspot.md). You pick what to bring and Orbit does the rest; a portal with tens of thousands of contacts is done in well under an hour, and you can keep using HubSpot while it runs. **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 their parent and child companies | Companies, matched by domain, with their lifecycle stage and the same parent/child links (a link whose other company was not imported is listed under the run's problems) | | 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) | Deals in the matching stage; 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 | | Opted-out and bounced contacts | The unsubscribe list, so nobody is emailed by mistake | Owners are matched to Orbit members by email, so invite your team first. Every record keeps its HubSpot id: running the import again updates what changed instead of creating duplicates, and a run that stops can be resumed where it left off. **Reading your portal.** The import reads HubSpot with a **service key** you create for it, never through the connected account: in HubSpot go to Settings → Integrations → Service keys (in some accounts, Development → Keys → Service keys), click **Create service key**, add the scopes below (a super admin is simplest: anyone else needs Developer tools access, and a key can only be given scopes its creator already has), then open the key, click **Show** and **Copy**, and paste it into the import dialog. HubSpot stopped new legacy private apps in October 2026; a token from a private app you already have still works. The key is used for this import only. It is deleted when the run completes or is cancelled; a failed run keeps it so you can resume without pasting it again. ``` 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 ``` Files attached to HubSpot records and marketing assets (templates, sequences, workflows) are not imported. To drive a migration from code instead, see [Migrating from another CRM](https://docs.useorbitcrm.ai/developers/migrating-from-another-crm.md). ## Before You Begin * A HubSpot account (Free, Starter, Professional, or Enterprise) * Admin or Super Admin permissions to install integrations * A form with at least an Email field ## Choose Your Setup Method You can sync form submissions to HubSpot in two ways. Choose based on your needs: > [card] Integration Page > > Connect HubSpot from your Integrations page and configure form-to-CRM field mappings directly. > > **Best for:** > > * Quick setup with OAuth authentication > * Simple 1:1 form-to-HubSpot mapping > * Syncing all submissions without filtering > > [Set up via Integration Page](#integration-page-setup) > [card] Workflows > > Add HubSpot as a destination in your workflows for advanced control over which leads sync. > > **Best for:** > > * Filtering by lead score or qualification > * Enriching data before syncing to HubSpot > * Combining with AI Agent qualification > > [Set up with Workflows](#using-hubspot-with-workflows) ### Integration Page vs. Workflows: Which Should You Use? **Integration Page** Use the Integration page when you want to send **all form submissions** directly to HubSpot without any filtering. * Simple form-to-HubSpot mapping * No need for lead qualification first * Fastest setup for basic CRM sync **Workflows** Use Workflows when you need **filtering, enrichment, or AI qualification** before sending to HubSpot. * Filter by lead score or qualification * Enrich leads before syncing (Clay, etc.) * Use AI Agent to qualify first [Learn more about Workflows](#using-hubspot-with-workflows) ## Integration Page Setup Connect HubSpot to OrbitForms using OAuth and configure which forms sync to your CRM. ### Step 1: Connect Your HubSpot Account **1. Go to Integrations in OrbitForms** From your dashboard, click "Integrations" in the left sidebar. `Dashboard → Integrations (left sidebar)` **2. Find HubSpot** Scroll down or search for "HubSpot" in the integrations list. `Search or scroll to find HubSpot` **3. Click "Connect HubSpot"** Click the HubSpot card, then click the "Connect HubSpot" button. `Click on HubSpot card → Connect HubSpot` **4. Sign in to HubSpot** You'll be redirected to HubSpot to sign in and authorize the connection. `Enter your HubSpot credentials` **5. Grant Permissions** Allow OrbitForms to access your HubSpot account. We only request the minimum permissions needed to create contacts and companies. `Click "Allow" to authorize` > [!NOTE] > > **Secure OAuth Connection** > > OrbitForms uses OAuth 2.0 to connect to HubSpot. We never see your password, and you can revoke access at any time from your HubSpot settings. ### Step 2: Configure a Form Mapping **1. Go to the Field Mapping tab** After connecting, you'll see the HubSpot configuration panel. Click the "Field Mapping" tab. `HubSpot config → Field Mapping tab` **2. Select a form to configure** You'll see a list of your forms. Click on the form you want to sync to HubSpot. `Click on a form from the list` **3. Choose what to sync** Toggle on "Contacts" to create contact records, and optionally "Companies" to create company records as well. `Toggle Contacts and/or Companies` **4. Map your form fields** For each form field, select the corresponding HubSpot property from the dropdown. Email is required for contacts. `Form field → Select HubSpot property` **5. Configure sync settings** Choose duplicate behavior (update, skip, or create new) and whether to add activity notes. `Set duplicate behavior and notes options` **6. Save Configuration** Click "Save Configuration" to save your mappings. The form will now sync to HubSpot. `Click "Save Configuration" button` ## Field Mapping Reference Map your form fields to HubSpot contact properties. The email field is required for contact creation. ### Contact Properties | Form Field | HubSpot Property | Required | | - | - | - | | Email | email | Required | | First Name | firstname | Optional | | Last Name | lastname | Optional | | Phone | phone | Optional | | Company | company | Optional | | Job Title | jobtitle | Optional | | Website | website | Optional | ### Company Properties | Form Field | HubSpot Property | Notes | | - | - | - | | Company Name | name | Required for company creation | | Company Domain | domain | Used for deduplication | | Industry | industry | Optional | | Company Size | numberofemployees | Optional | ### Using Custom Properties You can map form fields to any custom HubSpot property. First, create the property in HubSpot under Settings → Properties → Contact properties, then it will appear in the field mapping dropdown. > [!TIP] > > Click the refresh button in the field mapping panel to load newly created custom properties. ## Duplicate Handling Choose what happens when a contact with the same email already exists in HubSpot: > [card] Update (Default) > > Merge new data into the existing record. Properties from the form submission will update the contact. > [card] Skip > > Keep the existing record unchanged. The form submission won't modify any HubSpot data. > [card] Create New > > Always create a new record, even if the email already exists. May create duplicates. ## Using HubSpot with Workflows For advanced use cases, add HubSpot as a destination in your workflows. This gives you more control over which submissions get sent to your CRM. ### Use workflows when you need to: * Send to HubSpot only for qualified leads (after AI agent qualification) * Include enriched data in your HubSpot records (from Clay, Clearbit, etc.) * Use AI SDR to classify leads before adding to your CRM * Route different leads to different HubSpot lists or properties ### Adding HubSpot to a Workflow **1. Create or open a workflow** Go to Workflows in your dashboard and create a new workflow or open an existing one. `Dashboard → Workflows → Create/Edit` **2. Add a trigger** Set up a Form Submission trigger for the form(s) you want to sync. `Add Trigger → Form Submission` **3. Add any intermediate steps (optional)** Add AI Agent for qualification, Enrichment nodes, or Filter nodes as needed. `Add AI Agent, Enrichment, or Filter nodes` **4. Add HubSpot destination** Click the + button and select HubSpot from the destinations list. `+ Add Destination → HubSpot` **5. Configure the HubSpot node** Choose to create contacts, companies, or both. Map your fields to HubSpot properties. `Select record type → Map fields` **6. Save and activate** Save your workflow and toggle it to Active. Leads will now flow through your workflow to HubSpot. `Save → Toggle Active` ### Example: Qualified Leads Only A common workflow that only sends qualified leads to HubSpot: **Form Submission** → **AI Agent (Qualify)** → **Filter (Score > 70)** → **HubSpot** ### Syncing the Contact Owner The workflow HubSpot destination includes an optional **Sync contact owner** toggle. When enabled, the owner assigned to the contact in OrbitForms is mirrored to the HubSpot contact owner, so the right rep owns the record in both tools. The toggle is off by default — enable it per workflow where you want owners to stay in sync. ## Automatic Field Capture with HubSpot Pixel If you have the HubSpot tracking code installed, HubSpot can automatically capture form submissions — no API configuration needed. ### Embedded Forms If your Orbit form is embedded on a page where the HubSpot pixel is already installed, HubSpot may automatically capture form field data when visitors submit the form. Note that standard Orbit embeds render the form inside an iframe, which can prevent HubSpot from seeing the submission — test this on your site, and use the API integration if you need guaranteed delivery. ### Hosted Forms (Orbit URL or Custom Domain) If you're using an Orbit-hosted form URL, you can load your HubSpot tracking code on the form's thank-you page: **1. Open your form in Orbit** Open the form in the form editor. **2. Go to the Settings tab** In the form editor, open the "Settings" tab and make sure the thank-you mode is set to "Page". **3. Paste your HubSpot tracking code** Paste your HubSpot tracking code into the "Custom HTML / Tracking Scripts" box in the Thank You Page settings. **4. Save** Save — the tracking code loads on the thank-you page after each submission. ### Viewing Captured Submissions View your captured submissions in HubSpot under **Marketing → Forms → Non-HubSpot Forms**. > [!NOTE] > > **Note:** This is separate from the API integration. Use the pixel for simple automatic capture, or use the API integration for full control over field mapping and workflow automation. ## Troubleshooting > [!WARNING] > > **Contact not appearing in HubSpot?** > > Check that the email field is properly mapped and contains a valid email address. HubSpot requires a valid email to create contacts. > [!WARNING] > > **OAuth connection expired?** > > If your integration stops working, try clicking "Reconnect" in the HubSpot configuration panel. This will refresh your OAuth tokens. > [!WARNING] > > **Custom properties not appearing?** > > Click the refresh button in the field mapping panel to reload properties from HubSpot. Make sure the property exists in HubSpot under Settings → Properties. > [!WARNING] > > **Permission errors?** > > Ensure the HubSpot user who authorized the integration has Admin or Super Admin permissions. Limited users may not have access to create contacts or companies. > [!WARNING] > > **Duplicate contacts in HubSpot?** > > Check your duplicate behavior setting. If set to "Create New", it will create duplicates. Change to "Update" to merge data into existing records instead. ## Resources * [Creating Custom Properties](https://knowledge.hubspot.com/properties/create-and-edit-properties) * [HubSpot Workflows Guide](https://knowledge.hubspot.com/workflows/create-workflows) * [HubSpot Contacts API](https://developers.hubspot.com/docs/api/crm/contacts) * [HubSpot Collected Forms](https://knowledge.hubspot.com/forms/use-collected-forms) * [HubSpot Website](https://www.hubspot.com) *** ## Ready to Sync Your Forms to HubSpot? Connect HubSpot in minutes and start automatically syncing leads to your CRM. [Get Started](https://app.useorbitcrm.ai/signin) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.