HubSpot Integration

Connect HubSpot to use it as your team's CRM. Once connected, you can link HubSpot companies and contacts to tasks, boards, roadmap projects and River pages. HubSpot stays the source of truth: Fishladder keeps a reference to each record and never edits it.

Connecting HubSpot

1. Go to Settings → Integrations.
2. In the HubSpot section, click Connect HubSpot.
3. You'll be redirected to HubSpot's OAuth screen. Authorize Fishladder to access your CRM data (contacts, companies, and deals).
4. Once connected, you'll see your HubSpot portal name and ID on the Integrations page.

Only team admins can connect or disconnect HubSpot.

HubSpot replaces the Fishladder CRM

While HubSpot is connected, Fishladder's built-in CRM is turned off for everyone on the team, admins included. It disappears from the app switcher, and the CRM pages, API endpoints and Claude connector tools stop accepting changes. This stops people from keeping a second, divergent set of companies and contacts. Your existing CRM data isn't deleted, and it comes back if you disconnect HubSpot.

Linking companies and contacts

Open a task, a roadmap project or a River page and find the HubSpot section. Click Link, search by name, domain or email, and pick the record. Each linked record opens in HubSpot. The same record can't be linked to the same item twice.

A board for a client

Link a HubSpot company to a whole board in Board settings (the settings icon in the board header). Every task on that board then counts as that company's — including tasks created later — which is what Slack channel alerts use to post “task created for Acme”. A task is a company's when the company is linked to the task, its board, or a roadmap project the task is linked to.

Who can link

• Anyone who can edit the item (a member or admin with access to that module) can link and unlink records. Viewers see links but can't search HubSpot.
• Links on tasks and boards follow restricted boards: someone who can't open a board can't see, add or remove HubSpot links on it or its tasks.
• Unlinking only removes the reference — nothing changes in HubSpot — so members can unlink through the API too, where every other delete is admin-only.

From the CLI, Claude and the API

• From the terminal: fish hubspot search acme, then fish hubspot link task <taskId> <hubspotId>. Use project or page instead of task (pages accept the short ID from fish river pages or a title), and add --contact for contacts. Needs CLI v0.19.0 or later.
• From Claude: ask it to link a HubSpot company to a task, board, roadmap project or page. The connector offers search_hubspot, link_hubspot_record, list_hubspot_links and unlink_hubspot_record.
• API: GET /api/v1/hubspot/search?type=company&q=acme, and GET/POST/DELETE on /api/v1/tasks/{id}/hubspot-links, /api/v1/tracker/projects/{id}/hubspot-links (boards), /api/v1/projects/{id}/hubspot-links and /api/v1/river/pages/{id}/hubspot-links.

Sync Rules

Sync rules define what data flows from Fishladder to HubSpot and how fields are mapped. Each rule connects a Fishladder source type to a HubSpot object type.

Source Types

• Project — Roadmap projects and local initiatives
• Initiative — Strategic initiatives
• Goal — Team goals

HubSpot Object Types

• Deal — HubSpot deals (sales pipeline)
• Company — HubSpot companies
• Contact — HubSpot contacts

Creating a Sync Rule

1. On the Integrations page, scroll to the HubSpot section and click Add Sync Rule.
2. Give the rule a name (e.g. “Projects → Deals”).
3. Select the source type (Project, Initiative, or Goal).
4. Select the HubSpot object type (Deal, Company, or Contact).
5. Configure field mappings — map Fishladder fields (title, status, dates, etc.) to HubSpot properties. The wizard shows available HubSpot properties for the selected object type.
6. Click Save to create the rule.

Running a Sync

Once a sync rule is created, click Sync Now to push matching Fishladder records to HubSpot. The sync creates new HubSpot records for items that haven't been synced before, and updates existing records that have changed.

Each sync run is logged in the Sync Log, which shows:

• Status (success, error, or partial)
• Records processed, created, and updated
• Any errors encountered
• Timestamp

Managing Sync Rules

• Enable/Disable — Toggle a rule on or off without deleting it.
• Edit — Update the rule name, field mappings, or filters.
• Delete — Remove a sync rule. This does not delete any records already created in HubSpot.

Disconnecting

To disconnect HubSpot, click Disconnect on the Integrations page. This removes the OAuth connection and all sync rules, and turns the Fishladder CRM back on. Records already synced to HubSpot are not affected. Links are kept but hidden, and they reappear if you reconnect the same HubSpot portal.

Permissions

Fishladder requests read and write access to HubSpot contacts, companies, and deals. The OAuth scopes requested are:

• crm.objects.contacts.read / write
• crm.objects.companies.read / write
• crm.objects.deals.read / write