HubSpot
Connect a HubSpot account to Floqer to import records into lists, look up and enrich records mid-workflow, and write results back, all over a secure OAuth 2.0 connection.
How to connect
| Authorizing user | Best suited to | Scope of access |
|---|---|---|
| An individual HubSpot user | Establishing a connection quickly, in a few clicks | The records that user can see in HubSpot |
| A dedicated integration user | Organizations that require a tightly scoped connection, not tied to an individual. See Set up an integration user. | The permissions granted to the integration user |
Requirements, including who is permitted to connect, are covered in the FAQs, and Permissions and scope control describes how access is bounded once the connection is established.
Connect with a HubSpot login
- Log in to app.floqer.com and go to Connections → HubSpot.
- Select Connect to HubSpot. Floqer redirects to the HubSpot login page.
- Sign in to HubSpot and select the account to connect.
- On the HubSpot authorization screen, review the requested access, listed under OAuth scopes below, and select Connect app. HubSpot returns to Floqer.
- Verify the connection by searching for HubSpot in the connected apps section. It should show as connected.
- Open the connection to complete the setup:
- Toggle Enable for Org to make the connection available to every member of the workspace.
- Optionally toggle Set as Default to make this the default HubSpot connection.
- Select Save Changes.
Careful
The connecting user must be permitted to install apps in the HubSpot account: either a Super Admin, or a user granted App Marketplace access. Floqer can only view the records that user has access to.
Set up an integration user
Setting up a dedicated integration user for Floqer allows users to manage Floqer's access to HubSpot. Floqer operates as this user and cannot exceed its permissions, and removing the user terminates the integration. It is an ordinary HubSpot user rather than an API account, so it occupies a seat and signs in once to authorize Floqer.
Note
Steps 1 to 4 require a HubSpot Super Admin.
Step 1: Create the user
- Go to Settings → Users & Teams and select Create user.
- Enter an email address the organization controls, for example
floqer-integration@yourcompany.com, and send the invitation. - Accept the invitation from that mailbox and set a password. This user signs in once, to authorize Floqer.
Careful
Use a mailbox the team retains access to, such as a shared inbox or an alias. If the invitation cannot be accepted, the user can never authorize the connection.
Step 2: Assign a Core Seat
- Open the user under Settings → Users & Teams and select the pencil icon. The Manage user access screen opens.
- Expand Assign a seat and select Core Seat under Seat assignment.
Careful
A Developer Seat carries no CRM access. The permission options in the next step do not appear for one, and a connection made with it returns no records.
Step 3: Set the CRM permissions
The permissions granted here define the integration's scope, so grant only what the workflows require.
-
Expand Choose how to set access and select Manually assign permissions.
-
Expand Choose permissions and open CRM → CRM objects in the left-hand menu.
-
Switch each object the workflows use to ON, expand it, and set:
Permission Control Set to View Dropdown The level required on any object to be imported or looked up: Contacts and Companies, plus any of Deals, Leads, Calls, Meetings, or Tickets in scope. Create Toggle ON for any object the Create Object or Upsert Object actions write to. Edit Dropdown The level required on any object the Update Object or Upsert Object actions write to. Delete Dropdown None. Not used by Floqer. Merge Dropdown None. Not used by Floqer. The View and Edit levels are named after the object. For Contacts they are All contacts, Their team's contacts, Their contacts, and None. All exposes every record of that object, and the narrower levels restrict Floqer to that subset.
Each object shows its current setting beneath the name, for example
View (Their contacts) and Create. Objects the workflows do not use should be left OFF.
Note
Where View is narrower than All, the Unassigned checkbox beside it decides whether records with no owner are included. Leaving it clear hides every unowned record from Floqer.
Step 4: Permit the user to install apps
- Still under Choose permissions, open Account → Account settings in the left-hand menu.
- Switch App Marketplace access to ON so that the user can authorize Floqer.
- Open the Review tab, confirm the permissions, and save.
Note
App Marketplace uninstall access is a separate permission and is not required. Leaving it OFF prevents the integration user from removing apps from the account. A Super Admin can still disconnect Floqer at any time, as described under Revoking access.
Note
Floqer cannot reach anything outside this user's permissions, regardless of how a workflow is configured. Where a lookup returns fewer records than expected, the View level on that object is the first thing to check.
Step 5: Connect to Floqer as the integration user
- Sign out of HubSpot, or open a private browser window.
- Sign in to HubSpot as the integration user.
- Follow Connect with a HubSpot login. The connection is then established as this user, and no further interactive login is required.
HubSpot actions
Four HubSpot actions are available in the workflow action picker, searchable under "HubSpot":
| Action | Objects | HubSpot API call |
|---|---|---|
| Lookup Records | contacts, companies, calls, meetings, users | POST /crm/v3/objects/{object}/search |
| Create Object | contacts, companies, deals, leads, calls, meetings | POST /crm/v3/objects/{object}, plus PUT /crm/v4/objects/{object}/{id}/associations/default/{toObject}/{toId} where an association is configured |
| Update Object | contacts, companies, deals, leads, calls, meetings, users | PATCH /crm/v3/objects/{object}/{id} |
| Upsert Object | contacts, companies, deals, leads, calls, meetings | POST /crm/v3/objects/{object}/search on the selected unique property, then PATCH /crm/v3/objects/{object}/{id} or POST /crm/v3/objects/{object} |
Three contact-only actions, Create or Update Contact, Contact Lookup using Email, and Contact Lookup using Search Filters, have been retired from the action picker. Workflows already using them continue to run, and new workflows should use the object actions above.
HubSpot source
HubSpot is also available as a list source, selected when creating a list rather than from the action picker. It imports contacts or companies and keeps the list in sync on the schedule described under When does Floqer sync, and how often?.
| Import | HubSpot API call |
|---|---|
| Filtered by property | POST /crm/v3/objects/{object}/search |
| Every record of an object | GET /crm/v3/objects/{object} |
| Members of a HubSpot list | GET /crm/v3/lists/{listId}/memberships |
All three are paginated.
Security and access
Note
Security at a glance: Floqer connects over OAuth 2.0, so no HubSpot password is shared with Floqer. Access tokens refresh automatically, access is bounded by the requested scopes and the connecting user's permissions, and the connection can be revoked at any time from either side.
OAuth scopes
Floqer requests the 14 scopes listed below. To review them after connecting, open Floqer under Settings → Integrations → Connected Apps in HubSpot and expand Granted HubSpot permissions (14).
| Scope | HubSpot label | Why Floqer needs it |
|---|---|---|
crm.objects.companies.read | View properties and other details about companies. | Import, look up, and enrich companies. |
crm.objects.companies.write | Create, delete, or make changes to companies. | Create, update, and upsert companies. |
crm.objects.contacts.read | View properties and other details about contacts. | Import, look up, and enrich contacts. HubSpot governs calls and meetings through the contact scopes, so this also covers the Calls and Meetings objects. |
crm.objects.contacts.write | Create, delete, or make changes to contacts. | Create, update, and upsert contacts, calls, and meetings. |
crm.lists.read | View details about contact lists. | Offer the account's HubSpot lists as an import scope and check list membership. |
crm.objects.deals.read | View properties and other details about deals. | Look up deals and match them during an upsert. |
crm.objects.deals.write | Create, delete, or make changes to deals. | Create, update, upsert, and associate deals. |
crm.objects.leads.read | View properties and other details about leads. | Look up leads and match them during an upsert. |
crm.objects.leads.write | Create, delete, or make changes to leads. | Create, update, and upsert leads. |
oauth | View properties about the installing account including primary domain and user emails. | Required by HubSpot for every app that connects over OAuth. Floqer uses it to identify which account a connection belongs to. It grants no record access. |
crm.objects.owners.read | View details about users assigned to a CRM record. | Resolve owner identifiers to names in lookup results and setup screens. |
tickets | View, create, delete, or make changes to tickets. | Associate a created or upserted record with an existing ticket. |
crm.objects.users.read | Allows for reading User CRM object data. | Look up the User object. |
crm.objects.users.write | Allows for writing User CRM object data | Update the User object. |
Note
Floqer never deletes a HubSpot record. HubSpot has no write scope that excludes deletion, so every write scope is displayed as "Create, delete, or make changes to". Floqer calls no delete or archive endpoint on any object. The calls Floqer makes are listed under HubSpot actions.
HubSpot does not allow individual scopes to be declined, so all 14 must be granted for the installation to succeed. They define what Floqer is able to request. What it actually reaches is set by the connecting user, as described under Permissions and scope control.
Revoking access
Floqer's access can be terminated at any time:
- In HubSpot: go to Settings → Integrations → Connected Apps, open Floqer, and select Actions → Uninstall Floqer.
- In Floqer: disconnect the connection under Connections → HubSpot.
Permissions and scope control
Floqer operates as the HubSpot user who authorizes the connection and inherits that user's CRM permissions. HubSpot enforces those permissions on every API call: object-level View and Edit, ownership restrictions such as Their contacts or Their team's contacts, and field-level permissions all apply exactly as they would for that user in the HubSpot interface.
Nothing further is required. Floqer does not need Super Admin, and does not need Delete on any object.
Access can be limited at two layers:
- Configuration layer. Floqer requests only the properties selected in a source or action, and writes only the properties mapped in a create, update, or upsert step. Unselected properties are never requested and never stored.
- Permission layer, the enforceable one. Connecting with a dedicated HubSpot user whose permissions expose only the objects and records in scope. Anything outside that user's access is invisible to Floqer regardless of how a workflow is configured. See Set up an integration user.
Careful
The OAuth credential inherits the authorizing user's full reach. Where a Super Admin authorizes the connection, the credential is capable of reading records Floqer will never actually query. This is inherent to HubSpot's OAuth model rather than specific to Floqer, and it is the reason Floqer recommends a dedicated, scoped user: it collapses the gap between what Floqer accesses and what it could access.
FAQs
Which HubSpot accounts can connect?
Any account whose subscription includes every object listed under OAuth scopes. Where one is unavailable, HubSpot refuses the installation and names the missing scope. Custom objects are not supported.
Which HubSpot user can connect?
- Permission to install apps. The Super Admin role or the App Marketplace access permission.
- A Core Seat. A Developer Seat carries no CRM access, so a connection made with one returns no records.
- CRM permissions. View on any object the workflows import or look up, and Create or Edit on any object they write to.
Super Admin and delete access are never required. Permissions can be checked under Settings → Users & Teams.
Why does a lookup return fewer records than HubSpot shows?
Floqer sees only what the connecting user can see. The usual cause is View set to Their contacts or Their team's contacts, or a narrow View with Unassigned left clear. A Super Admin can widen it by opening the user under Settings → Users & Teams, selecting the pencil icon, and reviewing Choose permissions → CRM → CRM objects. Where results do not change, disconnect and reconnect HubSpot in Floqer.
Why does the User object return a permission error?
The User object requires the crm.objects.users.read and crm.objects.users.write scopes, added on 4 August 2026. Connections established before that date must be disconnected and reconnected once.
How is the integration built?
Floqer calls the HubSpot REST API at api.hubapi.com directly, server-to-server over HTTPS, authenticated with OAuth 2.0 as a public app. The current actions and sources use CRM v3, and v4 for associations; the retired Create or Update Contact action, in workflows that still run it, calls the legacy Contacts v1 endpoint.
- Nothing is installed in the HubSpot account. No workflows, properties, or objects are created. The only artifact is the app authorization itself, revocable under Settings → Integrations → Connected Apps.
- No middleware. No integration platform, extract-transform-load vendor, or broker sits in the path.
- Floqer initiates every read and write. The only HubSpot-initiated traffic is webhook notifications for contact and company creation and contact property changes. Each carries the account identifier, the record identifier, and the event type, and no record data.
How does data move between HubSpot and Floqer?
Into Floqer. The account's properties are read so that they can be selected in the setup screen, and the import is scoped to HubSpot lists or to record filters. On each run Floqer queries the selected properties only: filtered imports use the Search API, list-based imports read the memberships and then fetch the member records in batches, and full pulls page through the Objects API. Returned records are normalized, keyed by the HubSpot record identifier, and loaded into the list.
Back into HubSpot. A Create, Update, or Upsert Object step builds its payload from the properties mapped in that step, accepting either the option label or the internal value for dropdown and multi-select properties. Upsert first searches on the selected unique property, then updates the match or creates a record. The response is written back onto the workflow row. Where an optional association fails, the record is retained and the error is written to the row.
When does Floqer sync, and how often?
Floqer initiates all traffic, either on demand or on a schedule set on the source: every 5 minutes, twice daily, daily, every 2 days, weekly, monthly, or custom. Scheduled syncs are incremental, querying only records created or modified since the last successful run. A source can import existing records on its first run or take only new and updated ones, can be given a stop date, and can be paused or removed at any time.
Filtered imports use the Search API, which returns at most 10,000 records per query. Sources requiring more pull the full object and apply the filters within Floqer.
Does Floqer respect the HubSpot API limits?
Yes. Floqer pages through results 100 to 250 records at a time, depending on the endpoint, and paces its requests to stay within HubSpot's limits. Where HubSpot rate-limits a scheduled sync, Floqer backs off, honoring the retry interval HubSpot specifies, and retries before failing the run; a rate-limit response elsewhere is reported as an error on the affected request.
Which objects and properties does Floqer read and write?
There is no fixed list. Floqer defines no schema of its own and requires no specific property beyond the record identifier. Objects and properties are selected at configuration time, from the connected account.
- Read. The properties selected for an import or a lookup.
- Write. Only the properties mapped in a Create, Update, or Upsert Object step, plus one optional association.
Floqer reads no property that has not been selected and writes none that has not been mapped. There is no background crawling, no full-account sync, and no bulk export.
What data does Floqer store?
| Category | Typical items | Direction |
|---|---|---|
| CRM record identifiers | Record identifier, owner identifier, list memberships used to scope a source, created and modified dates | Read |
| Business contact data | Name, job title, business email, business phone, LinkedIn URL | Read and write |
| Company and firmographic data | Company name, domain, website, industry, employee count, revenue, location | Read and write |
| Custom properties | Any custom property selected or mapped | Read and write |
| Enrichment and AI-generated output | Enriched firmographic or contact attributes, scores, classifications, generated text | Write |
| Integration credentials | OAuth access and refresh tokens, the HubSpot account (portal) identifier and account details, and the email address of the Floqer user who established the connection | Held by Floqer |
| Operational data | Job status, timestamps, API responses and error messages | Held by Floqer |
What can Floqer see regardless of configuration?
- The account schema. Property names, types, and option lists for any object opened in the setup screens, including custom properties. This is metadata only, never record contents.
- The owner list. Identifier, name, and email address, used to display owner names alongside records.
- Lists. Names and identifiers when lists are selected, and the memberships of specific records where a source is scoped to lists.
- Account details. The account identifier, domain, and time zone, returned once at connect time.
How long is data from HubSpot retained?
For the duration of the engagement, so that workflows can operate on the records, results remain available for review and export, and re-running a workflow produces consistent output. Data is held in Floqer's managed cloud infrastructure and scoped to the customer organization.
Is customer data used for anything beyond serving the customer?
No. Floqer does not sell, license, or otherwise commercialize customer records, does not train, fine-tune, or evaluate models on them, and does not use them for benchmarking or product development. Customer data forms no part of any Floqer-owned dataset and is never offered to other customers.
How is data deleted?
Lists, workflows, and connections can be deleted at any time from within the product. For full deletion, send a written request to privacy@floqer.com. Deletion covers records ingested from the customer systems, workflow data derived from them, uploaded files, and the credentials of connected integrations. It is completed within 30 days of the request, with written confirmation once complete.
For questions not answered here, contact Floqer support at hello@floqer.com.