# HubSpot > HubSpot: what the collector reads, how to connect it, its permissions, its certification by Atlantic Agentic Labs and its security posture. Built, not certified Built and tested against recorded and synthetic responses (version 1.0.0, 10 November 2026). Not yet run against the vendor's sandbox or a client environment. Reads companies, contacts, deals and tickets from a HubSpot account, so commercial and service agents can answer from the account and ticket history. It reads in place, in your deployment; only ids, hashes and counts reach LightHouse. ## At a glance | Collector | HubSpot, version `1.0.0` | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | Reads | HubSpot: HubSpot CRM (CRM API v3) ([the vendor's documentation](https://developers.hubspot.com/docs/api/crm/understanding-the-crm)) | | Family | CRM | | Kind | CRM | | Ways to connect | Access token | | Scopes | - Read: `crm.objects.companies.read`, `crm.objects.contacts.read`, `crm.objects.deals.read`, `tickets` | | Read only | Yes, except: \[object Object] | | Vendor's API can move money | No | | Personal data | Contact, Content | | Hosts it may contact | `api.hubapi.com`, `app.hubspot.com`, `{host}` | | Vendor API versions | CRM API v3 | | Lowest engine version | `0.46.0` | ## What it reads - **Companies:** name, domain, industry, city, country, description. - **Contacts:** first and last name, email, job title, company. - **Deals:** name, stage, pipeline, amount, close date, description. - **Tickets:** subject, pipeline stage, priority, content. - Only the objects you name in `objects`. A whole portal is never the default. - Only the properties above, or the ones you name per object in `properties`, so a contact is not every field the portal holds about a person. - Changes only: each object is searched by `hs_lastmodifieddate`, oldest first, and paged by `after`. When a search reaches HubSpot’s 10,000-result ceiling, the query starts again from the newest change seen, so a first read of a large portal finishes rather than stopping at 10,000. HubSpot publishes no knowledge-base API, so articles are not read. Notes, emails, calls and attachments are not read. ## How to connect 1. In HubSpot, make a private app and give it the read scopes of the objects you will name (see Permissions). 2. In LightHouse, open **Setup and admin, Connectors**, choose **HubSpot**, and fill in `objects` and, if you want links back to HubSpot, `portal_id` (your account’s number). 3. Paste the private app’s access token. Your browser seals it to your deployment; LightHouse never sees it. The credential is JSON in the variable the source names (`HUBSPOT_CREDENTIAL` by default) with one field, `token`. ## Permissions - **Scopes:** `crm.objects.companies.read`, `crm.objects.contacts.read`, `crm.objects.deals.read` and `tickets`, for the objects you name. HubSpot states a private app’s scopes, and the deployment’s check reports them. - **What the collector does:** `GET` requests, and the CRM search, which HubSpot only offers as a `POST` with the query in the body (`/crm/v3/objects//search`). Nothing is created, changed or deleted. Its read-only test proves that on every change. - **One host:** every call goes to `api.hubapi.com`, fixed in the code; nothing in the configuration or the credential names another. ## Limits - CRM API v3. - Search answers at most 10,000 results to one query; the restart described above handles this, and ids already read are skipped. - Deletions (archived records) are found by listing ids every six hours; an archived record is removed from the corpus then, not at once. - `portal_id`, when given, only builds the link kept with each record (`app.hubspot.com`); that address is never contacted. - Property names must be lower-case HubSpot internal names. ## Data handling - Contacts and companies hold personal data (names, email addresses, job titles). Documents carry the `label` you give the source. - Content is read in place, in your deployment. LightHouse receives ids, hashes and counts, never the records, and never opens the credential. - The raw bytes of each response are cached in your deployment, named by their SHA-256, so any passage can be traced to what was served. ## Troubleshooting | What you see | What it means | What to do | | ----------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------- | | `credential variable 'HUBSPOT_CREDENTIAL' is not set` | The deployment holds no credential for this source | Connect HubSpot again in LightHouse | | `the hubspot credential has no token` | The credential lacks its `token` field | Re-enter the private app’s access token | | `not HubSpot property names for contacts: ...` | A property is not a lower-case internal name | Use HubSpot’s internal property names | | `portal_id is your HubSpot account's number` | `portal_id` is not a number | Give the account number, or leave it out | | `HTTP 401` or `HTTP 403` | The token is wrong, revoked, or lacks a scope | Check the private app’s scopes | | `HTTP 429` | HubSpot’s rate limit | Nothing; the collector backs off and the next run continues | ## Certification Each entry is a run by Atlantic Agentic Labs, newest first. Only a run against the vendor’s sandbox or a client environment certifies a collector; a certification lasts six months, or less if the vendor publishes an API version the collector does not list. See [How collectors are certified](/collectors/certification/). | Date | Collector | Engine | Vendor API | Method | Expires | | ---------------- | --------- | -------- | ---------- | ----------------------------------- | -------------- | | 10 November 2026 | `1.0.0` | `0.46.0` | CRM API v3 | Fixtures only: built, not certified | Not applicable | ## Security posture From the collector’s last scan on the default branch. What each line means, and what blocks a release: [Security posture](/collectors/security/). | Last scanned | 10 November 2026 | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Critical findings | 0 | | High findings | 0 | | Medium findings | 0 | | Low findings | 0 | | Info findings | 0 | | Release blocked | No | | Network allow-list check | Pass | | Read-only behavioural test | Pass | | SBOM (CycloneDX) | Produced | | Dependency licences | Pass | | Scanners | bandit 1.9.4, semgrep 1.181.1, pip-audit 2.10.1, osv-scanner 2.7.0, cyclonedx-py 7.5.0, pip-licenses 5.5.5, gitleaks repository job aal-secrets, hosts_check tools/hosts_check.py, read-only test pytest -m read_only | Source: https://docs.atlanticagenticlabs.com/collectors/catalogue/hubspot/