# HubSpot

> HubSpot CRM contacts, companies, deals, and tickets.

Lets an agent read and write CRM data in HubSpot.

## What it can do

| Method | What it does |
| --- | --- |
| `hubspot_create_contact` | Create a contact; deduplicates by firstname+lastname (+ company if set). |
| `hubspot_get_active_contacts` | Recently modified contacts (sorted by lastmodifieddate). |
| `hubspot_get_contact` | Get a contact by id. |
| `hubspot_update_contact` | Update a contact's properties. |
| `hubspot_create_company` | Create a company; deduplicates by domain or by exact name. |
| `hubspot_get_active_companies` | Recently modified companies. |
| `hubspot_get_company_activity` | List engagements (calls, emails, meetings, notes) associated with a company. |
| `hubspot_get_company` | Get a company by id. |
| `hubspot_update_company` | Update a company's properties. |
| `hubspot_create_deal` | Create a deal; set dealname, dealstage and pipeline ids via properties. |
| `hubspot_list_deals` | List deals (no fixed property list - works across portals). |
| `hubspot_update_deal` | Update a deal by id. |
| `hubspot_get_recent_conversations` | Recent conversation threads with messages (requires Conversations scopes). |
| `hubspot_list_pipelines` | List pipelines and stages - deals/tickets - with stage ids for create_deal. |
| `hubspot_associate_records` | Associate two CRM records using v4 default link. |
| `hubspot_create_note` | Create a CRM note and associate it with a contact / company / deal. |
| `hubspot_search_data` | HubSpot Search API across contacts, companies, or deals (structured query). |
| `hubspot_search_deals` | Search deals with filters (dealstage, closedate, amount, …) - find stale or overdue deals. |
| `hubspot_get_deal_activity` | Engagement history for a deal (last contact / outreach). |
| `hubspot_list_tasks` | List HubSpot tasks; filter by status (NOT_STARTED, COMPLETED, …) and due date. |
| `hubspot_get_tickets` | List tickets (no search call to avoid 400s on portals with custom property layouts). |
| `hubspot_get_property` | Read a CRM property definition. |

## How to get credentials

Use a HubSpot **Private App** access token.

1. Open your HubSpot account → **Settings** (gear icon) →
   **Integrations** → **Private Apps**.
2. **Create private app**, name it, go to **Scopes**.
3. Select the scopes the agent needs, at minimum:
   `crm.objects.contacts.read`/`write`,
   `crm.objects.companies.read`/`write`,
   `crm.objects.deals.read`/`write`, `tickets`, `crm.schemas.*`.
4. **Create app**, confirm, and copy the **Access Token** (starts with
   `pat-`).

## Fields to fill in FlyMyAI

| FlyMyAI field | Where it comes from |
| --- | --- |
| `HUBSPOT_ACCESS_TOKEN` | Private App → Access Token |

## Troubleshooting

- **`MISSING_SCOPE`** - open the Private App in HubSpot, add the scope,
  re-generate the token if prompted.
- **Custom properties not found** - HubSpot uses internal property names
  (often lowercase, underscores). Use `hubspot_get_property` to look up
  the exact name.

## Links

- [Create a HubSpot Private App](https://developers.hubspot.com/docs/api/private-apps)
- [HubSpot CRM API reference](https://developers.hubspot.com/docs/api/crm/understanding-the-crm)