Integrations · HubSpot

Connect HubSpot to noombat

A one-way, read-only connection. noombat reads your CRM on a schedule and writes nothing back. One private app, one token: a HubSpot super admin completes the setup in about 10 minutes.

Direction

noombat reads from it

Access

A private app holding read scopes only

Time

About 10 minutes

Who

A super admin

Cost on your side

Nothing: private apps come with every HubSpot tier, the free CRM included, and use no seat

Before you start

What to have ready.

  • A super admin: private apps are visible to super admins only, and that is the only HubSpot permission this setup needs.
  • Every HubSpot tier includes private apps: free CRM, Starter, Professional and Enterprise allow up to 20 per account, at no cost and using no user seat.
  • Your Hub ID (click your account name, top right; it is also the number in your app.hubspot.com URL) and your data hosting region (Settings > Account Defaults > Data Hosting). EU portals issue pat-eu1- tokens, US portals pat-na1-.
  • Marketing email opens and clicks need Marketing Hub or CMS Hub Professional or Enterprise; HubSpot offers the scope on those tiers only. That part is optional, and everything else works on any tier.

What noombat reads

What noombat reads from HubSpot, and why.

crm.objects.companies.readthe companies you sell to
crm.objects.contacts.readthe people at those companies, and with them the calls, meetings and notes logged on your records (HubSpot has no separate scope for those)
crm.objects.owners.readrecord owners, so activity and companies attribute to your reps
crm.lists.readwhich of your lists each company and contact belongs to
sales-email-readthe content of one-to-one emails logged on your records
crm.objects.deals.readoptional: deals and pipelines, so revenue outcomes connect back to the market
formsoptional: form submissions, if you capture demand through HubSpot forms
contentoptional: marketing email opens and clicks; Marketing Hub or CMS Hub Professional or Enterprise only

Setup

3 steps, about 10 minutes.

  1. 1Create the private app
  2. 2Copy the access token
  3. 3Send us the connection details
  1. 1

    Create the private app about 5 minutes

    A private app is HubSpot's built-in way to give one integration its own key with an exact list of permissions: auditable on its own, unaffected by staff changes, revocable in one click.

    Development > Legacy apps > Create legacy app

    On older portals the same screen sits under Settings > Integrations > Private Apps > Create a private app.

    • Name: noombat
    • Description: read-only CRM feed for noombat (optional; it helps the next admin know what this app is)

    On the Scopes tab, tick the read scopes from the list above. Tick the optional ones if you use those parts of HubSpot, skip the ones you do not, and tell us which.

    Click Create app and confirm. Scopes can be adjusted any time later; edits apply to the existing token at once, so a missed scope is a ten-second fix.

  2. 2

    Copy the access token about 1 minute

    (the app) > Auth > Show token > Copy

    The token starts with pat-na1- or pat-eu1- depending on your region. Use the Copy button rather than selecting the text: a surprising number of failed setups are a token that picked up a space or lost a character on the way.

  3. 3

    Send us the connection details about 2 minutes

    • The access token (pat-...)
    • Your Hub ID
    • Your data hosting region (EU, US)
    • Which optional scopes you skipped, if any

    Once the details arrive we run a read-only verification the same day, connecting with your token and checking that each object returns what it should, and confirm back to you. If anything is off, we name the exact setting to adjust; the table below lists everything it could be.

Troubleshooting

What you might see, and the fix.

Every row is a failure we have met or verified. If yours is missing, send it over.

What you seeWhyFix
403 MISSING_SCOPES: "This app hasn't been granted all required scopes to make this call"A scope from the list was left unticked. The response names the missing scope under requiredGranularScopes.Open the app > Scopes > tick it > Save. The existing token picks up the new scope at once.
The same MISSING_SCOPES error with the scope ticked, or the scope is absent from the pickerYour HubSpot tier lacks that feature. The content scope (marketing email events) needs Marketing Hub or CMS Hub Professional or Enterprise.It is optional for us: skip that scope and tell us, and we plan the connection around it.
401 INVALID_AUTHENTICATION: "Authentication credentials not found"The token was truncated or picked up whitespace when pasted, or it was rotated since you copied it.Re-copy with the Copy button on the app's Auth tab and check for spaces or line breaks.
Everything worked for weeks, then every call returns 401The token was rotated, or the app deleted. HubSpot emails every super admin when either happens.Send us the new token the secure way from step 3 and we are back the same day.
You cannot find the private apps page, or cannot create the appPrivate apps are visible to super admins only.Have a super admin run step 1. It is the only HubSpot permission this setup needs.
Association lookups fail with USER_DOES_NOT_HAVE_PERMISSIONSThe super admin who created the app was removed or downgraded since; HubSpot ties some calls to the creator.Rotate the token, or recreate the app, under an active super admin and send us the new value.
"Hub <your id> is unknown to this Hublet"Rare: stale routing state after HubSpot moved your portal between data centres.Rotate the token; the new one carries the current region and routing fixes itself.

Security and data

The questions a security review asks.

Is this read-only?

Yes, and HubSpot itself enforces it. The private app holds read scopes only. Every write endpoint checks for the paired .write scope, which the app lacks, so the platform rejects any write attempt. There is nothing to configure to get this guarantee; it is how HubSpot scopes work.

What does noombat read, and why?

Companies and contacts (who you sell to), deals (pipeline and revenue), the engagements logged on your records (calls, meetings, emails, notes), list memberships, form submissions and marketing email opens and clicks (how your market responds), and owners (who works what). noombat keeps a read-only mirror, scores your market against it, and connects the companies it names to the meetings and revenue that follow. History matters: the scoring learns from what already happened, which is why a forward-only feed such as a webhook is too little.

Can we keep specific properties private?

HubSpot's scopes are object-level, so a token cannot be limited to specific properties the way Salesforce field-level security works; HubSpot's own docs note that its user-facing property restrictions leave API access untouched. Two things do help. First, noombat requests the specific properties it uses, and we share the exact list. Second, on Enterprise, HubSpot's Sensitive Data feature gates any property you classify as sensitive behind dedicated *.sensitive.* scopes, which we never request, so those values are blocked to our token by the platform.

What does this cost on the HubSpot side?

Nothing. Private apps are included in every HubSpot tier, the free CRM included, with up to 20 per account, and a private app is an account-level credential rather than a user, so no seat is consumed. The one tier-dependent piece is the optional content scope (marketing email opens and clicks), which HubSpot offers on Marketing Hub or CMS Hub Professional and Enterprise; everything else works on any tier.

Could we send a webhook instead?

A webhook pushes one object's changes in real time and stops there: it sends changes from today on, while noombat learns from the existing history; each object needs an automation built and kept on your side; and a receiver ends up calling the API for the full record anyway. We add webhooks on top of API access for time-sensitive events when a customer asks.

How do we revoke access?

At once, from your side, in either of two ways: on the app's Auth tab choose Rotate and expire now (the old token dies immediately), or delete the private app (its token is permanently revoked). Nothing on our side can restore access. For a graceful handover, Rotate and expire later keeps the old token alive for 7 days while the new one is delivered.

Can we audit what noombat reads?

Yes. The private app's page in HubSpot has an API call log covering the past 30 days: every request with its method, endpoint and response code, filterable and exportable as CSV. Because noombat is the only thing using this app's token, everything in that log is attributable to us alone. HubSpot keeps the calls themselves in the log, without request or response payloads.

Is our data safe with noombat?

Your data is kept apart from every other customer's, in a schema of its own, encrypted in transit and at rest, read through connections that write nothing back, and deleted when we part ways. Data-processing terms written for a security review, for teams in the EU and in the US. We walk through them with your security team on request.

Checked against HubSpot's own documentation. Last updated . Questions, or a policy in the way: integrations@noombat.ai