Skip to main content

​
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

Anything defined in the HubSpot API 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.
1

Open private apps in HubSpot

In HubSpot, click Settings (the gear icon), then in the left sidebar go to Integrations, then Private Apps.
2

Create the app

Click Create a private app and give it a name (for example “Serval Integration”) and a description.
3

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.
4

Copy the access token

Click Create app, then copy the access token.
The built-in connection test reads your account’s user settings, so settings.users.read is effectively required for the health check to pass.
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.

​
Connect in Serval

1

Open the connect form

In Serval, open the Hubspot integration’s connect form.
2

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.
3

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.
4

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.
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”.

​
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.
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.

​
Gotchas and troubleshooting

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).
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.
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.
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.
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.
“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.
Need help? Contact support@serval.com for assistance with your HubSpot integration.