#Current status

The HubSpotConnector class (in src/lib/crm-connectors/providers/hubspot.ts) implements every capability it declares. connect and refreshToken perform real OAuth token exchanges against HubSpot, and pushLead, updateLead, fetchLeads, pushNote, createTask, pushDeal, updateDeal, fetchDeals, and syncVendorEnrollment all make live calls to the HubSpot v3 CRM API. Requests flow through the shared BaseConnector.request helper, which retries with exponential backoff and tolerates empty / 204 responses.

#Why it matters

Advisors who already run their book of business in HubSpot want Olyron's insurance-native tooling — vendor enrollment feeds, plan changes, member rosters — to flow back into the pipeline they report on. The connector is a two-way sync (bidirectional: true) so leads and deals stay consistent in both systems rather than being copied once and drifting.

A distinguishing capability is syncVendorEnrollment: Olyron normalizes carrier/vendor enrollment attributes (plan, status, change type, effective and termination dates) and records them as a Note on the member's HubSpot contact, so the change lands directly on the contact's activity timeline — something a generic CRM sync does not do.

#How the connect flow works

The OAuth handshake follows the standard authorization-code grant:

1. 1
   Start from the Integrations screen

   Go to Dashboard → Settings → Integrations (/dashboard/settings/integrations). Because HubSpot is implemented: true, its card shows an "Available" badge and a Connect HubSpot button that routes to /dashboard/settings/integrations/hubspot/connect.
2. 2
   Pick what to sync

   On the connect page you can toggle Vendor enrollment sync (on by default) and choose which vendor fields to include. The options are Plan Name, Status, Effective Date, Termination Date, and Premium; the first three are selected by default. These preferences are stashed in sessionStorage under crm_vendor_sync_preferences as { enabled, fields }.
3. 3
   Authorize in HubSpot

   Olyron builds the authorize URL with getAuthUrl("hubspot", redirectUri, state) and redirects you to https://app.hubspot.com/oauth/authorize. The state value is "<tenantId>:<timestamp>" and is also saved to sessionStorage (crm_oauth_state) for CSRF protection. The redirect URI is ${window.location.origin}/api/crm-connectors/hubspot/callback.
4. 4
   HubSpot calls back

   After you grant access, HubSpot redirects to /api/crm-connectors/hubspot/callback?code=...&state=.... The route parses the tenantId from state, confirms a signed-in Supabase user, and exchanges the code for tokens by calling connector.connect({ auth_code: code }).
5. 5
   Connection is saved

   On success the callback inserts a row into crm_connections with AES-256-GCM-encrypted access and refresh tokens, expires_at, and status: "active", then redirects to the field-mapping step with ?connection_id=<id>&success=true.

https://app.hubspot.com/oauth/authorize
  ?client_id=<HUBSPOT_CLIENT_ID>
  &redirect_uri=<origin>/api/crm-connectors/hubspot/callback
  &scope=crm.objects.contacts.read crm.objects.contacts.write
         crm.objects.deals.read crm.objects.deals.write
         crm.objects.notes.read crm.objects.notes.write
         crm.objects.tasks.read crm.objects.tasks.write
  &state=<tenantId>:<timestamp>

#Configuration

To stand up the connector you need a HubSpot public app and the following environment variables. HUBSPOT_CLIENT_ID is read by getAuthUrl and connect(); the client secret and redirect URI are used by the token exchange in connect(); refreshToken() needs the client ID and secret.

HUBSPOT_CLIENT_IDstring

Public app client ID. Injected into the authorize URL and sent in both the authorization-code and refresh-token grants.

HUBSPOT_CLIENT_SECRETstring

App client secret used when exchanging the authorization code and refreshing tokens at POST https://api.hubapi.com/oauth/v1/token.

HUBSPOT_REDIRECT_URIstring

The registered callback URL. Must equal <origin>/api/crm-connectors/hubspot/callback and match the redirect URI used to obtain the code.

CRM_ENCRYPTION_KEYstring

Secret used to derive the AES-256-GCM key that encrypts stored CRM tokens. Applies to all connectors, not just HubSpot. Required in production — the app refuses to store tokens without it.

Token storage is encrypted at rest

OAuth access and refresh tokens are stored in crm_connections.access_token_enc / refresh_token_enc. The encryptToken / decryptToken helpers in sdk.ts use AES-256-GCM (authenticated encryption) with a 32-byte key derived by SHA-256 from CRM_ENCRYPTION_KEY. Ciphertext is stored in this format:

v1:gcm:<iv_b64>:<tag_b64>:<ciphertext_b64>

#What syncs and how fields map

The connector declares these capabilities, each backed by a live HubSpot v3 CRM call. All requests send an Authorization: Bearer <access_token> header.

The webhooks capability is declared true, but the connector does not currently register HubSpot subscriptions itself — sync is driven by the push/pull operations above.

Contact (lead) field mapping

pushLead and updateLead send these standard HubSpot contact properties, then merge in any tenant field mappings and custom_fields. Non-standard values such as status and source are not pushed directly — route them through field mappings to real HubSpot properties to avoid 400s. fetchLeads reads the properties below and maps hs_lead_status back to status.

fetchLeads returns up to query.limit (default 100) contacts. With query.search it POSTs to /objects/contacts/search matching the term against email EQ or lastname EQ; otherwise it GETs /objects/contacts and uses query.offset as the HubSpot after cursor.

Deal field mapping

fetchDeals requests the dealname,amount,dealstage,closedate,pipeline properties (default limit 100, offset → after) and maps amount back to a number.

#Notes, tasks, and associations

In HubSpot, engagement objects (notes, tasks) must be associated to their contact or deal. The connector creates the object and attaches it using HubSpot-defined (v4) association type IDs in the same request.

pushNote writes hs_note_body (prefixed with the note title when present) and hs_timestamp, associating the note to the given contact ID via type 202. An additional Note → Deal type (214) is defined in the connector but pushNote currently only associates notes to contacts.

Task enums

createTask sends hs_task_subject, hs_task_body, hs_task_status, hs_task_priority, and hs_timestamp (the task's due date, or now). Olyron statuses and priorities are normalized to HubSpot's enums:

#Vendor enrollment sync

syncVendorEnrollment(payload) records a vendor/carrier enrollment change on the HubSpot activity timeline. It builds a plain-text summary from the payload (member name, plan, status, change type, effective and termination dates, and a free-text description), then:

• If payload.member_external_id is set, it calls pushNote(member_external_id, …) so the enrollment appears as a Note on that member's contact, titled Vendor enrollment: <vendor_name> (association type 202).
• If there is no linked contact, it POSTs an unassociated note to /crm/v3/objects/notes with the vendor name and summary inline, so the record still exists in HubSpot.

#Limits and troubleshooting

• HubSpot access tokens are short-lived (the connector stores expires_at from the expires_in HubSpot returns); refresh tokens do not expire. refreshToken() performs the refresh_token grant using HUBSPOT_CLIENT_ID and HUBSPOT_CLIENT_SECRET.
• HubSpot's rate limit is roughly 100 requests per 10 seconds per account. Every connector call goes through BaseConnector.request, which retries with exponential backoff (up to 3 attempts) and skips retries on 4xx except 429.
• The success redirect and the Active Connections "Configure" button both target /dashboard/settings/integrations/<provider>/map-fields, but that field-mapping route is not built yet — only the connect route exists under [provider].
• State validation in the callback currently only checks that state is present; full CSRF verification against the stored crm_oauth_state is still marked "validate this properly" in the code.

Callback error codes

If the OAuth flow fails, the callback redirects back to /dashboard/settings/integrations with an ?error= query parameter: