hubspot.

when the instance publishes its hubspot apps, the card shows connect hubspot: you pick the portal, approve, and you are connected — no key to create, no scope to tick. pick the tab first: it decides which kind of connection you make.

no "connect hubspot" button on a tab: the instance has no hubspot app for that kind of connection yet — the service key below works the same.

hubspot authenticates via a service key. ⚠️ hubspot stops letting you create *private apps* (on 28/09/2026 for new accounts, 26/10/2026 for existing ones — changelog); a private app made before keeps working, and its token is pasted the same way.

in hubspot, open development → keys → service keys (on some accounts: settings → integrations → service keys), click create service key (super admin or developer tools access needed), name it and tick the scopes (names as hubspot's scope list spells them — each comes as .read and .write):

there is no crm.objects.tickets scope (without .read/.write): if a guide told you to tick it, tick crm.objects.tickets.read instead.

⚠️ if your key (or private app) predates the lists tools, it only has the crm.objects.* scopes and hubspot_list will answer 403. that does not mean your key is wrong: reopen it in hubspot and add the scope. adding a scope does not change a private app's token; if you rotate the key in hubspot, its new value replaces the old one: paste it again in oto (connector hubspot).

test the connection tells you more than "it authenticates": it reads, family by family, which scopes the token holds (connected, tickets scope missing). a missing family does not turn the connection red — the rest keeps working. it also names the portal the key reads (identity: portal id, region, account type).

⚠️ the expected token is the service key's value, or a private app's access token (both of the form pat-<region>-…). if you paste something else — typically an oauth *refresh token*, a long base64 blob starting with Ci… — hubspot answers 401 `EXPIRED_AUTHENTICATION` with a misleading message along the lines of "expired 20697 day(s) ago" and an expiry date of january 1st, 1970. nothing expired: a refresh token has no expiry field, so sent as a bearer it is read as expired since the epoch. that message means "this is not an access token", not "your token got old".

### troubleshooting — 403 MISSING_SCOPES on one object type

contacts and deals answer, but tickets (or lists, or pipelines) answer 403 `MISSING_SCOPES`, with hubspot's message "the scope needed for this api call isn't available for public use". that message is misleading: the scope exists, it is just not ticked on your key. the refusal oto returns names the scope to add — tick it on the service key (or in the private app's scopes tab) and save. nothing to fix in the call.

### troubleshooting — 400 PROPERTY_DOESNT_EXIST on a write

a create or update names a property your portal does not have (e.g. linkedin_url on a company, where hubspot's own property is linkedin_company_page). hubspot refuses the whole call, nothing is written. the refusal oto returns names the unknown properties: read the real internal names with hubspot_property (op list) and fix the procedure, or create the property (op create) if it should exist. in hubspot_push_rows, the batch stops at the first row (stopped: hubspot_property_doesnt_exist, unknown_properties) instead of failing every row the same way.

query and edit your hubspot crm (contacts, companies, deals, tickets) from claude.

### merging duplicates — irreversible

⚠️ a hubspot merge cannot be undone. always run it first with dry_run=true: it reads the survivor and each duplicate (name and domain, or email; how many contacts and deals each one carries) and tells you what would happen, without writing anything.

### segments = lists

in hubspot, a "segment" is a list: there is no separate segments api. hubspot_list covers them.

three list types, chosen at creation and not changeable afterwards:

emptying a list (clear_members) and deleting it (delete) accept dry_run=true: it tells you what would go without touching anything. a deleted list stays restorable for 90 days (op restore).

### properties — read before writing

hubspot internal names are not the interface labels (dealstage, not "Deal Stage"), and a dropdown only accepts its declared values. hubspot_property (op list) gives the real schema of an object type — on a fresh portal, that is already 404 properties on contacts, 45 of them enumerations. this is what makes the create/update of hubspot_object reliable and the filter_branch criteria of a dynamic list, which reference properties by internal name.

op list returns one compact row per property (name, label, type, field type, group, options) and leaves out hubspot's hidden internal ones — include_hidden=true keeps them, verbose=true gives the full cards. a deal's stages belong to a *pipeline*, not to the dealstage property: their options are filled from the pipelines, grouped by pipeline.

### pipelines and stages

### website visitors

hubspot_visits reads who came to your site, latest first. three sources, and they do not measure the same thing:

what hubspot needs on its side, per its own documentation (we have not yet read a portal with tracking on):

what hubspot does not expose: the pages a *company* read. the buyer intent card shows them in hubspot; the api only carries the two 30-day counts. on a company, page paths need a visitor-identification tool that writes them.

an empty op companies answer says why: its diagnosis counts the tracked companies — zero means tracking was never turned on, not that nobody came.

to run it on a schedule ("new visitors since the last run"), pass since = the last run's time minus a few minutes, and deduplicate on the record id: hubspot's search index lags a few moments behind a write. a segment works too — a list filtered on recent intent signals, read with hubspot_list (op members, with properties), whose rows carry the date each company entered it.

### searching: order and pages

this connector accepts multiple comptes: each stored credential becomes a named account (one name per compte), at your level, your team's or your org's.