Connect HubSpot
You create a Private App inside HubSpot, choose which scopes to grant it, and paste its token into MarqIQ. HubSpot and Marketo are the only two tools where MarqIQ writes hidden fields onto your forms and builds the source-tracking workflow for you. If you want to know what you are granting before you start, read How connecting a tool works.
Before you start
Permissions required
You need a HubSpot user who can create a private app in the portal whose data you want. MarqIQ reads the portal id back from the token and shows it on the connection, so you can check it against the portal you meant.
Plan required
Connecting works on every plan. The field and form operations under Tool Operations need Pro or above and do not appear on Starter. Creating the tracking properties needs only a paid subscription, so a Starter workspace does it from the UTM Field Validation section on the HubSpot page instead.
Create the token in HubSpot
In HubSpot, go to Settings → Integrations → Private Apps, or open app.hubspot.com/l/private-apps
If your portal cannot create private apps, go to Settings → Integrations → Service Keys → Create key instead, at app.hubspot.com/l/service-keys. Prefer a private app: its name shows in a record’s change history, and a service key’s does not.
Click Create a private app.
Name the app MarqIQ.
HubSpot attributes every change to the app that made it, so a named app makes MarqIQ's writes show as MarqIQ in a record's history rather than as an unnamed integration.
Grant `crm.objects.contacts.read`.
This is the only scope MarqIQ cannot connect without. It tests your token against HubSpot's contact-properties endpoint the moment you connect and refuses the connection if HubSpot says no, naming the scope it wants.
Grant the optional scopes for the parts of MarqIQ you want.
A token missing an optional scope does not break the connection. Most screens quote HubSpot's own refusal back to you rather than showing a silent zero.
- `crm.objects.deals.read` — the deals themselves. Without it no deal syncs at all and every pipeline figure is empty.
- `crm.objects.companies.read` — companies, and which company each deal belongs to.
- `crm.schemas.deals.read` and `crm.schemas.companies.read` — your custom deal and company properties on top of the standard ones.
- `crm.objects.owners.read` — owner names, and the email each owner signs in with. Without it owners appear as ids and “my leads” cannot find you. The email is kept in your workspace’s own cache, used only to match the person signed in to their owner, and never shown.
- `crm.objects.contacts.write` — writing back to contacts. Leave it off and MarqIQ reads only.
- `crm.schemas.contacts.write` — creating the UTM tracking properties and their property group.
- `forms` — your forms by name, and adding hidden tracking fields to them.
- `automation` — reading your workflows, and creating the Source Tracking workflow. Not read-only.
- `content` — your marketing emails and landing pages, and creating drafts from Template Studio. Not read-only.
- `business-intelligence` — HubSpot's traffic analytics, and the submission count per form.
- `email-events` — individual sends, opens, clicks and bounces per person.
- `files` — uploading images into your File Manager, for templates MarqIQ builds.
Copy the access token.
It begins pat-na1- for a North America portal. It is long-lived: there is no OAuth round trip and nothing renews on a schedule.
Paste it into MarqIQ
Open Connected Tools in MarqIQ and click the HubSpot card.
The page is headed Integrations, and HubSpot sits under the CRM heading.
Paste the token into Access Token.
Click Connect HubSpot.
MarqIQ verifies the token, reads the portal id back from it, and shows your company name, hub domain, timezone, currency and data region. Check the portal is the one you meant before you go further.
If the tool is already connected, the button reads Update token instead. Use it to replace a token without losing your field mappings.
Leave the tab open while the first sync runs.
Connecting starts the sync on its own. The chunk loop runs in your browser, so the status line says "keep this tab open". Close the tab and the run stops where it is. The next sync, manual or scheduled, carries on from the saved cursor.
Read the result line.
A first load finishes with "Fully synced — N records". Later runs say "Up to date — N changes since your last sync". Compare N against what HubSpot shows under Contacts.
Note
The very first sync in a new workspace can report that the workspace's database is still being created. The message on screen says it takes under a minute; twenty seconds is typical. MarqIQ waits and retries four times on its own. If it gives up, wait a few minutes and click Sync now.
What comes across
- Contacts, with every property on them. MarqIQ asks HubSpot for your property definitions first, so custom properties arrive with the standard ones.
- Companies, deals and engagement events, from a second sync that runs on the same connection and on its own scheduled lane.
- Owners, so people appear by name rather than by id.
- Pipelines and their stage definitions, including each stage's configured probability.
- Forms, marketing emails, landing pages, workflows and traffic analytics — each only when its scope is granted.
- Individual email events per person, with the `email-events` scope.
- Property change history, which is what the Field discipline analysis judges.
The property ceiling
MarqIQ keeps up to 3,000 properties per object. A core list — email, name, phone, mobile phone, company, job title, lifecycle stage, lead status, owner, HubSpot's own source properties, the recent-conversion properties and a few dates — is always included, so a very large portal cannot lose those to the ceiling.
What you can do with HubSpot and not with most tools
- Source tracking setup — a guided flow that creates the UTM properties, adds them as hidden fields to the forms you choose, and then builds the workflow that locks in first touch. HubSpot and Marketo are the only two tools this flow supports.
- Create N missing creates a whole group of tracking properties at once, rather than you making them by hand and mapping to them. Pipedrive, Zoho CRM, Mailchimp, Marketo, Pardot and Adobe Journey Optimizer can do this too. Salesforce cannot — it needs the Metadata API, so you create those fields in Setup yourself.
- Two attribution properties, Updated by and Last MarqIQ update, created the first time MarqIQ writes a standardised or enriched value, where your token lets it create properties. Filter on Updated by in HubSpot to list the contacts those writes reached. A change set and the first-touch backfill do not fill them.
- Writing hidden tracking fields onto your live marketing forms.
- A Source Tracking workflow built inside your own portal, named "[MarqIQ] Source Tracking — Copy Most Recent to First Touch". It enrols contacts where First Touch Medium is unknown and Most Recent Medium is known, then chains eight edit-record actions. It arrives switched off for you to review, and rebuilding it deletes the one MarqIQ made before.
- Property labels resolved to what you see on screen, rather than internal values.
- Per-record change history, which is what lets Field discipline and Forecast accuracy run at all.
The properties themselves are the seventeen MarqIQ tracks: nine under Most Recent UTM Fields and eight under First Touch UTM Fields. You can see which of them exist in your portal on the UTM Field Validation section of the HubSpot page.
What MarqIQ will not do in HubSpot
- It never deletes a contact, company or deal.
- It sends no email and publishes no landing page, and the workflow it builds arrives switched off. Three things are live as soon as you ask for them: a field added to a form, a pushed template, and an uploaded image, which is public.
- A change set only ever fills a property that is empty when it writes, and so does the first-touch backfill: it reads each record from HubSpot just before it writes.
- Normalisation and enrichment do replace values you already have, and neither shows you every record first. What MarqIQ will never do to your data says what each one shows.
If it did not work
The sync reports success but every deal figure is empty
Why: Your token has `crm.schemas.deals.read` but not `crm.objects.deals.read`. The schema scope sounds as though it covers deals and does not. This is the scope people miss most often.
Fix: Add `crm.objects.deals.read` to the private app in HubSpot, copy the token again, paste it into Access Token, click Update token, then click Sync now.
The connection is refused and the message names a scope
Why: The token lacks `crm.objects.contacts.read`, so HubSpot refuses the contact-properties call MarqIQ makes to verify it.
Fix: Add that scope to the private app, copy the new token, and connect again. HubSpot issues a new token whenever you change scopes, so the old one will not carry the change.
Owners show as long numbers instead of names
Why: `crm.objects.owners.read` was not granted, so MarqIQ holds the owner id and has nothing to resolve it to.
Fix: Add the scope in HubSpot, update the token in MarqIQ, then click Sync now.
The connection succeeded but Field Mapping is not under Tool Operations
Why: Field mapping is a Pro-and-above feature, so a Starter workspace never sees that screen. It is a plan limit, not a connection fault.
Fix: Move to Pro or above, or map your properties from the UTM Field Validation section on the HubSpot page.
A custom property you created in HubSpot yesterday is not in MarqIQ
Why: Property discovery runs as part of a sync, so a property created after the last run has not been seen yet.
Fix: Click Sync now on the HubSpot page, then look for the property in Unified field catalog.
The sync stops with "Another sync is already running for this workspace — it will finish on its own."
Why: The scheduled run holds this workspace. Only one sync per tool runs at a time, by design.
Fix: Nothing. Your data is being refreshed right now. The message is shown in green rather than red for that reason.
Next steps
Related articles
Was this article helpful?