> 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 syncing to HubSpot Marketing Events. 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 Marketing Event sync
* **Read HubSpot deals for attribution** — HubSpot deals attached to linked Accounts flow into the [Post-Event tab](/help-center/the-hub/managing-events/reading-the-post-event-tab.md) so event ROI reflects the pipeline the event actually drove. Mobly reads deals; it doesn't create or update them.
* **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 sync events to Marketing Events)
* 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. [**Registration**](#registration-mappings) — set the HubSpot Marketing Event status a lead gets at each Mobly registration state (see below).
4. [**Labels**](/help-center/labels/how-to-use-mobly-labels.md) — group leads inside Mobly by qualifier value, event, activation, or scan count. Mobly-side only.
5. [**Sync mode**](/help-center/integrations/crm/sync-modes.md) — Automatic by default; switch to Manual on the Connect tab if needed.

## Registration mappings

The **Registration** tab is where you set the org-wide default HubSpot Marketing Event status for each of Mobly's three lead-registration states.

{% hint style="info" %}
**Registration is available on select orgs today.** The tab appears once your org has the Activations feature enabled. Contact your CSM about turning it on if you don't see it.
{% endhint %}

Mobly tracks a lead through three registration states as they move through your event:

| Mobly state      | When a lead reaches it          |
| ---------------- | ------------------------------- |
| **Registered**   | Lead signed up before the event |
| **Checked-in**   | Lead checked in at the door     |
| **Live Capture** | Lead scanned on the floor       |

For each state, pick the HubSpot Marketing Event participation status you want that state to map to (e.g., "Registered," "Attended," "Cancelled"). When a lead hits that state in Mobly, the linked HubSpot Marketing Event's participation status for that lead updates to the mapped value.

**How the mappings are used.** These are **org-level defaults** — every Event or Activation you link to a HubSpot Marketing Event picks up these three mappings automatically. You can override any state on an individual Event or Activation if that particular booth or dinner uses different statuses.

**When to use it.** If you use HubSpot Marketing Events and want your reps' HubSpot filters (or dashboards, or downstream automation) to distinguish "who pre-registered vs walked in vs got scanned on the floor," set these once here and every event uses them by default.

## 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.

**Make Mobly contacts Marketing Contacts automatically.** By default, contacts synced from Mobly land as non-marketing contacts in HubSpot. Two ways to change that:

* **Simplest (recommended).** In HubSpot, go to **Settings → Integrations → Marketing Contacts** and enable it for the Mobly integration. Every Mobly-synced contact now lands as a Marketing Contact automatically.
* **Conditional.** If you only want *some* Mobly contacts to be Marketing Contacts (e.g., only Hot leads, or only leads from certain events), build a HubSpot workflow: trigger on contact created / updated with a Mobly-side signal (Mobly ID present, Last Scanned Event set, a Lead Source = Mobly value, etc.), and add a **Set as Marketing Contact** action step. No other actions needed.

## 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)
* [CRM campaign sync](/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)