> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# HubSpot

> HubSpot is a CRM and marketing platform; Serval connects to it with a private app access token and calls the HubSpot API on demand from your workflows.

## About HubSpot

HubSpot is a CRM and marketing platform covering contacts, companies, deals, tickets, users, and communication preferences. Serval connects to your HubSpot account with a private app access token and calls the HubSpot API only when a workflow or health check runs - anything your private app's scopes cover is reachable through a single generic API request action. There are no prebuilt per-object helpers and no background sync. You will see this integration listed as "Hubspot" in Serval.

**Authentication:** HubSpot private app access token, entered in Serval as an "API Key". One long-lived token - no OAuth sign-in and no token refresh.

**Data sync:** On demand only. Serval never syncs or polls HubSpot in the background; data is read or written only when a workflow step or health check runs.

## What the HubSpot integration enables

| Capability                                                     | Description                                                                                                                                                                                                                                           |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Call any HubSpot API endpoint                                  | The "Hubspot API request" action sends any request to HubSpot using your stored token. Workflows can read, create, update, and search contacts, companies, deals, and tickets, request specific fields, and page through results up to 100 at a time. |
| User and team management                                       | List, create, update, and remove HubSpot users (looked up by user ID or email address), and list roles and teams - including which roles carry a paid seat.                                                                                           |
| "Unsubscribe from Marketing Emails" (installable workflow)     | Takes a contact's email address, reads their current email subscription statuses, and unsubscribes them from each active subscription type one by one, reporting the result for each.                                                                 |
| "Provision HubSpot User with Core Seat" (installable workflow) | Takes an email, first name, and last name, creates the user in HubSpot with the default core seat, and sends them a welcome email to set their password.                                                                                              |

Anything defined in the [HubSpot API](https://developers.hubspot.com/docs/reference/api/overview) can be accessed through Serval.

## Get your credentials

Serval authenticates as a HubSpot **private app**. You create the app in HubSpot, grant it the scopes (permissions) your workflows need, and paste its access token into Serval. HubSpot's official walkthrough is the [private apps guide](https://developers.hubspot.com/docs/guides/apps/private-apps/overview).

<Steps>
  <Step title="Open private apps in HubSpot">
    In HubSpot, click **Settings** (the gear icon), then in the left sidebar go to **Integrations**, then **Private Apps**.
  </Step>

  <Step title="Create the app">
    Click **Create a private app** and give it a name (for example "Serval Integration") and a description.
  </Step>

  <Step title="Grant scopes">
    On the **Scopes** tab, grant the scopes your workflows will call. At minimum, for the built-in connection test and the user management capability, grant `settings.users.read`, `settings.users.write`, `settings.users.teams.read`, and `settings.users.teams.write`. Add CRM object scopes if your workflows touch contacts, companies, deals, or tickets, and communication preferences scopes if you plan to install the "Unsubscribe from Marketing Emails" workflow - confirm exact names against HubSpot's scope catalog in the Scopes tab.
  </Step>

  <Step title="Copy the access token">
    Click **Create app**, then copy the access token.
  </Step>
</Steps>

<Note>
  The built-in connection test reads your account's user settings, so `settings.users.read` is effectively required for the health check to pass.
</Note>

<Tip>
  You can add scopes to the private app at any time later. The existing token picks up scope changes automatically - you only need to update the token in Serval if HubSpot rotates it.
</Tip>

## Connect in Serval

<Steps>
  <Step title="Open the connect form">
    In Serval, open the Hubspot integration's connect form.
  </Step>

  <Step title="Enter an Instance Name">
    "Instance Name" is a free-text label for this connection and becomes its display name. Neither field on this form is marked required, so you will not see an asterisk or a "This field is required" error.
  </Step>

  <Step title="Paste your token into API Key">
    "API Key" is a password field for the private app access token. There is no format check and the token is not tested when you submit - a blank or mistyped value saves successfully. After saving, the value is shown masked with only the last 4 characters visible; the integration's settings form offers a pencil icon (and the configure dialog a **Replace** button) to enter a new one.
  </Step>

  <Step title="Submit, then verify">
    Submit the form, then run the "Test HubSpot Connection" health check right away (see below) - that is the first moment an invalid token will surface.
  </Step>
</Steps>

<Warning>
  When you edit this connection later for any reason - even just renaming it - you must re-enter the **full** access token in "API Key" before saving. Saving the edit form without retyping the token erases the stored credential and silently breaks the connection. Leaving "Instance Name" blank on an edit is safe (it keeps the existing name); leaving "API Key" untouched is not. When you click the pencil icon to replace the token on the settings form, the emptied field's placeholder reads "Enter new value".
</Warning>

## Verifying the connection

The integration ships one health check:

* **Test HubSpot Connection** - asks HubSpot to list the users in your account settings using the stored token. On success it reports "Successfully authenticated with HubSpot". On failure it reports "Unable to connect to HubSpot. Please verify your API key is valid and has the necessary scopes."

A pass confirms the token is valid and can read user settings - it does not confirm any other scope.

<Tip>
  If the health check is green but a workflow still fails with a permission error, the private app is missing a scope for that specific call. HubSpot's error response lists the missing scopes - add them to the private app in HubSpot and re-run. You do not need to re-enter the token in Serval.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Re-enter the full access token whenever you edit the connection">
    The update form does not keep your stored token when the "API Key" field is left masked or blank - saving any change without retyping the full token stores an empty credential and silently breaks authentication. The break shows up as the health check failing with "Unable to connect to HubSpot. Please verify your API key is valid and has the necessary scopes." Always paste the complete token again before saving an edit. Only "Instance Name" is safe to leave blank (it keeps the existing name).
  </Accordion>

  <Accordion title="A passing health check does not prove your scopes are sufficient">
    The connection test only reads user settings. Workflows that touch CRM records, communication preferences, or user creation can still fail with permission errors if the private app lacks those scopes. HubSpot's error message includes the list of missing scopes - grant them on the private app in HubSpot. The existing token picks up scope changes; you only need to update Serval if HubSpot rotates the token itself.
  </Accordion>

  <Accordion title="Nothing validates the token at connect time">
    Neither connect form field is required, and the token is never tested when you save - a blank or mistyped token saves successfully and only fails later at the health check or first workflow run. Run the "Test HubSpot Connection" health check immediately after connecting.
  </Accordion>

  <Accordion title="The token is only ever sent to api.hubspot.com">
    Serval attaches your access token only to requests bound for HubSpot's official API host (api.hubspot.com). Custom workflow steps must use standard HubSpot API paths; a request to any other host will not carry the credential and will fail to authenticate.
  </Accordion>

  <Accordion title="User provisioning always assigns a core seat and sends a welcome email">
    The "Provision HubSpot User with Core Seat" workflow always sends a welcome email and deliberately assigns no role, so HubSpot grants the new user the default core seat with basic contact permissions. To assign a specific role or paid seat, build a custom workflow that sets the role - and note that assigning or unassigning a role with a paid seat requires the billing-write scope on the private app.
  </Accordion>

  <Accordion title="Unsubscribe workflow opts contacts out one subscription type at a time">
    "Unsubscribe from Marketing Emails" uses HubSpot's legacy email system: it reads every subscription type for the given email address and unsubscribes each active one individually, reporting per-type results (succeeded, already unsubscribed, or failed). It takes an email address rather than a contact record, so it also works for people who exist only in HubSpot's email system. Both installable workflows require installer approval by default.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your HubSpot integration.