HubSpot | Alephant Documentation

What it indexes

The HubSpot connector can create primary documents for four CRM object types: tickets, companies, deals, and contacts. All four are selected by default; the Admin form lets you choose a subset.

Primary object	Indexed content
Tickets	Ticket content, subject as the document identifier, priority metadata, and available associated contacts, companies, deals, and notes.
Companies	Name, domain, industry, location, description, and available associated contacts, deals, tickets, and notes.
Deals	Name, amount, stage, close date, pipeline, description, and available associated contacts, companies, tickets, and notes.
Contacts	Name or email identifier, company, job title, phone, location, and available associated companies, deals, tickets, and notes.
Files	Attachments and file bodies are not downloaded by this connector. Note bodies are converted from HTML to plain searchable text.

Object selection controls which types become primary documents. It does not exclude related CRM data from those documents: for example, a ticket document can still contain an associated company or deal summary even when companies or deals is not selected as a primary type.

Prerequisites

Create or obtain a HubSpot access token for the approved account.
Grant the token read access to every selected primary object type.
Grant access to the integration identity endpoint so OpenCore can resolve the HubSpot portal ID used in citation URLs.
Grant read access to associations and to the related contacts, companies, deals, tickets, and notes that should appear in primary documents.
The connector worker only needs HTTPS access to HubSpot API hosts, including api.hubapi.com; it does not open citation URLs.
End-user browsers must be able to reach app.hubspot.com to open HubSpot citations.
Decide whether related-object summaries and note bodies are acceptable inside each selected primary document.

Credentials

Method	OpenCore credential values	Authentication behavior
HubSpot access token	`hubspot_access_token: <HUBSPOT_ACCESS_TOKEN>`	OpenCore sends the token to the HubSpot APIs and calls the integration identity endpoint to store the portal ID.

The current Admin credential has one access-token field. It does not initiate a browser OAuth flow or accept a client ID, client secret, refresh token, portal ID, or custom HubSpot Base URL.

Configure in OpenCore

In the Admin panel, open Connectors, select HubSpot, and create the access-token credential.
Under Object Types, select at least one of Tickets, Companies, Deals, or Contacts. All four are selected by default.
Review the related records that can be embedded in each selected primary type. Object-type selection does not create an association privacy boundary.
Choose Private and assign OpenCore groups for restricted CRM data. Use Public only when every OpenCore account may search every successfully indexed primary and associated record.
Set refresh and cleanup options, create the connector, and run the first indexing attempt.

The standard Admin connector runs poll_source. Only when the effective poll start is exactly Unix epoch 0 does HubSpot remove the time bounds and perform a full cursor-based scan of each selected primary type. If Indexing Start makes the effective start nonzero, the first attempt uses a Search API time window instead. Later polls use each object’s last-modified property and their scheduled start/end window.

Permissions

The HubSpot token determines what OpenCore can ingest, but HubSpot users, teams, object ownership, and record-level access are not synchronized into OpenCore. The connector does not provide a slim permission document path or query-time HubSpot access check.

After indexing, search access is controlled by the connector’s OpenCore Private groups or Public mode. A user who can search a primary document can also search the associated object summaries and note text embedded in that document, even if the user could not open those records in HubSpot. Use a least-privilege token, select only required primary types, and split sensitive datasets across separate connectors and OpenCore groups where the token’s visibility permits.

Verify

Create the credential and confirm OpenCore resolves the expected HubSpot portal ID.
Record the effective first poll window, run the first sync, and search for one record from every selected primary object type. With a nonzero effective start, check a record inside the Search API time window and one well before it; with epoch 0, check an older expected record from the cursor scan.
Confirm an unselected type does not produce independent primary documents.
Inspect a representative primary document for associated records and a note. Confirm related data is acceptable even when its type is not selected as a primary type.
Open a citation link with a HubSpot-authorized browser session and confirm the portal and object are correct.
Test every assigned OpenCore group because HubSpot access is not re-evaluated at search time.

Troubleshooting

Symptom	What to check
Credential creation cannot resolve the portal	Replace the invalid or expired access token and allow the integration identity endpoint. The portal ID is discovered, not entered manually.
A selected object type returns 403	Grant the token read access to that CRM object type and its requested properties.
Primary documents exist but related sections are missing	Grant association and related-object read access. Association and batch-read failures are logged and the primary document can continue without those sections.
Notes are missing	Grant access to note associations and note batch reads. The connector reads note body and timestamp properties, not file attachments.
An unselected object appears in search	Check whether it is an associated section inside a selected primary document. Primary-object selection does not remove related summaries.
First-run coverage or duration is unexpected	Check Indexing Start and the attempt’s effective poll start. An effective start of epoch 0 performs a cursor scan of all selected primary objects; a nonzero start uses the bounded Search API path. Confirm the recorded window before changing scope, then reduce primary types or choose the intended Indexing Start as appropriate.
Polling is API-call intensive	Search results do not include inline associations, so changed records can require separate paginated association requests and batch reads. HubSpot rate limits are locally throttled and 429 responses are retried up to the configured retry ceiling.
A poll window contains at least 10,000 records	OpenCore continues from the last modified timestamp. Records sharing the boundary timestamp can be indexed twice; if the timestamp is missing, unparseable, or does not advance, records after the cap can be missing. Narrow the change window and verify counts.
Users can search records they cannot open in HubSpot	This is expected because HubSpot ACLs are not synchronized. Restrict the connector with OpenCore groups or split the source.