Skip to main content

​
Overview

HubSpot appears in Config -> Connections under Dev Tools. Genesis supports one saved auth mode:
  • api_key — a HubSpot Service Key or Private App bearer token.
After setup, Genesis tests the connection against api.hubapi.com and reads the portal identity from HubSpot account details. On Snowflake Native App / SPCS deployments, HubSpot connections declare egress for api.hubapi.com.

​
Setup workflow

1

Open the HubSpot connector

Go to Config -> Connections, choose Dev Tools, then select HubSpot.
2

Create a Service Key or Private App token

In HubSpot, open Settings -> Integrations and create a Service Key (preferred) or Private App token. HubSpot has deprecated private apps in favor of Service Keys for single-account API access; either works in Genesis as a static bearer token.
3

Grant required scopes

The token must include every scope Genesis needs. During the post-save Test Connection step, Genesis lists the required scopes and provides Copy required scopes so you can paste them into HubSpot’s scope picker.Required scopes:
  • crm.objects.companies.read
  • crm.objects.companies.write
  • crm.objects.contacts.read
  • crm.objects.contacts.write
  • crm.objects.deals.read
  • crm.objects.tickets.read
  • crm.schemas.companies.read
  • crm.schemas.contacts.read
  • crm.schemas.custom.read
  • account-info.security.read
The account-info.security.read scope is required because connection testing and merge tenant binding read the portal identity from /account-info/v3/details. The deals and tickets read scopes are required because both are readable object types; without them those reads fail with MISSING_SCOPES.
4

Enter connection fields

Paste the token into Service Key or Private App Token. Optionally enable approval-gated merge settings (see below). Save the connection.
5

Test, egress, and save

On SPCS deployments, complete egress preflight in the post-save guide. Save the connection and run Test Connection. If scopes are missing, HubSpot returns a 403 with MISSING_SCOPES — add the scopes Genesis lists, update the token in HubSpot, and retry.
If your deployment uses outbound allowlists or external access controls, allow Genesis to reach api.hubapi.com.

​
Connection fields

​
api_key

​
Approval-gated merge

Merges are opt-in per connection and irreversible. Enable Enable Approval-Gated Merge (merge_enabled) only when operators are ready to govern duplicate consolidation. When merge is enabled, set Merge Review Fields (JSON) on the connection. The policy must include:
  • version — non-empty string bound into the approval digest.
  • preview_fields — non-empty list of HubSpot property names shown on the human review surface.
HubSpot determines final field values during a merge, so do not set survivorship rules. Every review field is stored in the approval digest. Example:
Genesis supports merging contacts and companies only, with one survivor and exactly one loser per merge. HubSpot’s merge endpoint accepts a single objectIdToMerge; HubSpot determines the resulting record id and redirects both input ids to it.

​
Merge workflow

  1. Preview — hubspot_connector with PREVIEW_MERGE, or POST /api/crm/hubspot/merge/preview. Writes nothing; returns projection and digest.
  2. Request approval — REQUEST_MERGE_APPROVAL or POST /api/crm/hubspot/merge/approvals with optional expected_digest from the preview.
  3. Human approve — POST /api/crm/hubspot/merge/approvals/{approval_id}/approve. Only a genuinely authenticated human can approve; agents cannot substitute. There is no approval screen yet — approval is made through this authenticated API route.
  4. Execute — EXECUTE_APPROVED_MERGE or POST /api/crm/hubspot/merge/approvals/{approval_id}/execute with the bound connection name.
Approval lifetime defaults to 3600 seconds and is capped by hubspot.max_approval_ttl_seconds in App Config (default 86400). Connection-specific API behavior is listed in the provider-neutral CRM merge endpoints.

​
What it enables

After setup, Genesis can use hubspot_connector_tools for bounded CRM reads and writes on contacts and companies, with read-only access to deals and tickets. Administrators can extend readable and writable object types through the hubspot.extra_objects App Config setting. With merge enabled, agents and operators can run the preview → approval → execute merge path for duplicate contacts and companies.