> For the complete documentation index, see [llms.txt](https://help.getmobly.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.getmobly.com/help-center/integrations/crm/hubspot/setup-guide.md). # HubSpot setup guide Mobly's HubSpot integration syncs every captured-and-enriched lead into your HubSpot Contacts (and optionally Companies), with field mapping, qualifier mapping, and per-event campaign sync. Connection runs through Mobly's new integration platform, so there's no Connected App or API key to manage on your side. ## What you can do * **Sync leads to HubSpot Contacts** — every Mobly-captured lead becomes a Contact in HubSpot, matched by Contact ID or Email (creates a new Contact if no match) * **Sync to Companies** — Mobly creates or updates the lead's Company by domain or company name * **Map any Mobly field to any HubSpot property** — including custom properties * **Use HubSpot picklists** for qualifier mapping — single-select and multi-select properties both work * **Log lead activities as HubSpot Engagements** — outreach actions in Mobly (Pulse sequence emails, calls, meetings, LinkedIn touches, SMS, manual notes) appear on the matching Contact as Email, Call, or Meeting engagements. See [Finding Mobly activities in your CRM](/help-center/integrations/crm/finding-activities-in-your-crm.md) for the per-action breakdown * **Sync to HubSpot Marketing Events** — see [Connecting HubSpot Marketing Events to Mobly Events](/help-center/integrations/crm/hubspot/connecting-marketing-events.md) for per-event campaign sync configuration * **Toggle Automatic vs Manual sync** — see [Sync modes](/help-center/integrations/crm/sync-modes.md) ## What's not supported (yet) * **Custom HubSpot objects** other than Contact and Company aren't currently mapped from Mobly * **Deal sync** — Mobly doesn't create or update Deals; only Contact + Company. If you need lead-to-deal automation, build it in HubSpot using a workflow keyed off the Mobly-created Contact * **Multi-integration** — running HubSpot alongside another CRM in the same Mobly org isn't supported today (one CRM per org) ## Before you connect You'll need: * A **HubSpot user with admin access** (or at minimum, write access to Contacts and Companies, plus read access to your Marketing Events if you'll use campaign sync) * A **Mobly admin account** to view and configure Integrations * About 15 minutes for setup if your HubSpot properties are already in good shape If your HubSpot has very lightly customized properties, plan extra time to align Mobly fields to existing HubSpot properties (or create new HubSpot properties for Mobly-specific fields like enrichment metadata). ## Connect the integration 1. Go to **Integrations → HubSpot** in Mobly 2. Click **Connect** on the Connect tab 3. Sign in to HubSpot when prompted, pick the right HubSpot account if you have access to multiple, and approve the requested permissions Detailed walkthrough of the Connect flow: see [Connecting your CRM](/help-center/integrations/crm/connecting.md). After connecting, the Connect tab will show your HubSpot account as **Connected** with a globe icon. ## Configure data flow Work through the tabs in order: 1. [**Mapping**](/help-center/integrations/crm/field-mapping.md) — match Mobly fields to HubSpot properties for Persona (Contact) and Company. Use **Set Defaults** for a quick start. 2. [**Qualifiers**](/help-center/integrations/crm/qualifiers.md) — define qualifiers and map values to HubSpot picklist options. 3. [**Campaigns**](/help-center/integrations/crm/campaign-mapping.md) — link Mobly events to HubSpot Marketing Events if you use them. 4. [**Sync mode**](/help-center/integrations/crm/sync-modes.md) — Automatic by default; switch to Manual on the Connect tab if needed. ## HubSpot-specific configuration tips **Property types matter.** Mobly's field type badges (TEXT, EMAIL, URL, PHONE) should align with HubSpot property types. Misaligned types most often surface as `DATA_FORMAT_VALIDATION` errors in Reconciliation. **Multi-select vs single-select.** HubSpot's multi-select dropdowns accept multiple Mobly qualifier values when joined by your event name separator. Single-select dropdowns reject multi-value sends — use them only for Mobly qualifiers configured as **Single**. **"Restrict to Picklist Values" in Mobly qualifier mapping.** When mapping a Mobly qualifier to a HubSpot picklist, every Mobly qualifier value needs a corresponding picklist option in HubSpot. Unmapped values trigger `NO_TAG_MAPPING` errors in [Reconciliation](/help-center/integrations/crm/reconciliation.md). **Using open-text fields for qualifier flexibility.** If your HubSpot picklists change frequently and rigid mapping is painful, map qualifiers to HubSpot open-text properties instead. Less validation, more flexibility. **Creating Mobly-specific properties.** A common pattern is a "Mobly" group of properties in HubSpot — `Mobly First Capture Date`, `Mobly Event`, `Mobly Booth Scan Count`, etc. Create them in **HubSpot → Settings → Properties → Create property** before mapping in Mobly. ## Troubleshooting If a synced lead shows up in **Reconciliation → Failed**, see [Fixing HubSpot sync errors](/help-center/integrations/crm/hubspot/troubleshooting.md) — there's a section per error category with the fix. For broader integration questions (auth, permissions, what data lands where), revisit [Connecting your CRM](/help-center/integrations/crm/connecting.md) and [How data flows from Mobly to your CRM](/help-center/integrations/crm/how-data-flows.md). ## Related articles * [Connecting your CRM](/help-center/integrations/crm/connecting.md) * [Sync modes](/help-center/integrations/crm/sync-modes.md) * [Field mapping](/help-center/integrations/crm/field-mapping.md) * [Qualifiers](/help-center/integrations/crm/qualifiers.md) * [Mapping campaign fields](/help-center/integrations/crm/campaign-mapping.md) * [Reconciliation](/help-center/integrations/crm/reconciliation.md) * [Fixing HubSpot sync errors](/help-center/integrations/crm/hubspot/troubleshooting.md) * [Connecting HubSpot Marketing Events to Mobly Events](/help-center/integrations/crm/hubspot/connecting-marketing-events.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.getmobly.com/help-center/integrations/crm/hubspot/setup-guide.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.