> For the complete documentation index, see [llms.txt](https://support.suptask.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.suptask.com/integrations-automations-and-workflows/integration-guides/hubspot.md).

# Hubspot

Pull customer data and manage Hubspot directly from tickets

The HubSpot connector links Suptask to your HubSpot account. Once connected, the AI Assistant on an Inbox can look up contacts, companies, deals and tickets in HubSpot, and - depending on the permissions you grant - update & manage them directly from a ticket.

To connect it, you create an OAuth app in your **HubSpot developer account**, then paste the resulting **Client ID** and **Client Secret** into Suptask. This guide covers every step.

***

### What you can use it for

* **Customer context on a ticket** - an agent asks who the requester is, which company they belong to, and what their account looks like, without leaving Slack.
* **Answer account questions** - the Assistant answers questions about plan, owner, renewal date or deal stage straight from HubSpot.
* **Keep HubSpot up to date** - log a note on a contact or company, update a property, or create a follow-up from the ticket conversation.
* **Sales and support in one place** - support tickets from a customer channel become visible to the team that owns the relationship.

***

### Before you begin

You'll need:

* An **admin** role in Suptask.
* A **HubSpot account**. This is where the OAuth apps are created.
* A **Super Admin** user in the HubSpot account you want to connect.
  * HubSpot only allows Super Admins to install an app.
* The **Inbox** you want to connect HubSpot to.

What you'll do:

* Create an app in your HubSpot developer account
* Add the Suptask redirect URL
* Select the scopes the app should request
* Copy the Client ID and Client Secret into Suptask
* Choose permissions and authorize

{% hint style="info" %}
Keep the Connect HubSpot window in Suptask open in a separate browser tab. You'll switch back to it at the end.
{% endhint %}

***

### Step 1 - Open your HubSpot account

1. Go to [HubSpot](https://app.hubspot.com/) and sign in to your **account**.
2. If you don't have one yet, create a account.

{% hint style="warning" %}
An OAuth app can't be created inside a regular HubSpot account. If you don't see an Apps section, you're signed in to a standard account rather than a developer account.
{% endhint %}

***

### Step 2 - Create the app

1. In the developer account, open **Apps**.
2. Click **Create app**.
3. On the **App info** tab, enter a name, for example `Suptask AI`, and a short description.
   * This name and description are shown to the user who installs the app, so keep them recognizable for your team.
4. Save.

***

### Step 3 - Add the redirect URL

1. Open the **Auth** tab of your app.
2. Under **Redirect URLs**, add:

```
https://ai-prod.suptask.com/mcp/oauth/callback
```

3. Save.

{% hint style="warning" %}
Enter the URL exactly as shown, with no trailing slash. A mismatch is the most common cause of authorization errors.
{% endhint %}

***

### Step 4 - Select scopes

Still on the **Auth** tab, select the scopes your app should request. The scopes decide what Suptask is allowed to read and change in HubSpot.

A common starting point:

| Scope                        | Gives access to                 |
| ---------------------------- | ------------------------------- |
| `oauth`                      | Required for all OAuth apps     |
| `crm.objects.contacts.read`  | View contacts                   |
| `crm.objects.companies.read` | View companies                  |
| `crm.objects.deals.read`     | View deals                      |
| `crm.objects.owners.read`    | View record owners              |
| `tickets`                    | View and manage HubSpot tickets |

Add the matching `.write` scopes only if you want the Assistant to be able to change records, for example `crm.objects.contacts.write`.

{% hint style="warning" %}
The scopes selected in HubSpot must cover everything Suptask requests during authorization. If a scope is missing, HubSpot blocks the installation with a scope error.
{% endhint %}

***

### Step 5 - Copy your Client ID and Client Secret

On the **Auth** tab, HubSpot shows your app credentials.

1. Copy the **Client ID**.
2. Copy the **Client Secret**.

{% hint style="info" %}
Treat the Client Secret like a password. Both values stay available on the Auth tab if you need them again later.
{% endhint %}

***

### Step 6 - Connect in Suptask

1. In the Suptask Web App, open the **Inbox** you want to connect HubSpot to.
2. Go to the **AI Assistant** settings and open **Connectors**.
3. Add the **HubSpot** connector.
4. Paste your Client ID into **OAuth Client ID**.
5. Paste your Client Secret into **OAuth Client Secret**.
6. Select the **Permissions** you want to grant (see the next section).
7. Click **Authorize**.
8. A HubSpot sign-in window opens. Sign in as a **Super Admin**, select the HubSpot account to connect, and approve access.

When it's done, the connector status changes to connected.

***

### Choosing permissions

Each permission maps to what the Assistant can do in HubSpot. Grant only what your team needs.

* **Contacts (read-only)** — View contacts and their properties.
* **Contacts (read/write)** — Create and update contacts.
* **Companies (read-only / read/write)** — View or manage company records.
* **Deals (read-only / read/write)** — View or manage deals and deal stages.
* **Tickets (read-only / read/write)** — View or manage HubSpot tickets.
* **Owners (read-only)** — View which user owns a record.

{% hint style="info" %}
Start with read-only access. You can reopen the connector and grant read/write later if needed.
{% endhint %}

The connector provides a set of Tools to the AI Assistant. Permissions are set per Tool, so you can let the Assistant read your CRM without allowing it to change anything.

***

### Use different HubSpot access per Inbox

Each Inbox in Suptask has its own connector. Different teams can therefore work against HubSpot in different ways:

* **Customer Support Inbox** — read contacts, companies and deals to give agents account context.
* **Sales Support Inbox** — read and write deals so the Assistant can log outcomes from the ticket.
* **Internal Inbox** — no HubSpot connector at all.

A ticket in one Inbox only reaches the HubSpot permissions granted on that Inbox's connector.

***

### How to use the integration

This connector is used by the AI Assistants you set up in Suptask. You can both read and manage HubSpot content from a ticket.

Read more about how AI Assistants work to understand all use cases.

{% content-ref url="/pages/EMXzCysY1oz2JPFXI8gH" %}
[AI Assistants](/suptask-ai/ai-assistants.md)
{% endcontent-ref %}

***

### Troubleshooting

* **Authorization fails with a scope error** — a scope requested by Suptask isn't selected on the **Auth** tab of your HubSpot app. Add it and try again.
* **Redirect URL mismatch** — confirm the redirect URL in HubSpot is exactly `https://ai-prod.suptask.com/mcp/oauth/callback`.
* **Installation blocked** — the user installing the app isn't a Super Admin in the HubSpot account, or lacks access to one of the requested scopes.
* **The Assistant can't find a record** — the record may sit outside the connected HubSpot account, or the needed read permission wasn't granted on the connector.
* **The Assistant can't update a record** — only read permissions are granted. Reopen the connector and enable the matching read/write permission.
* **The connector stopped working** — the app may have been uninstalled from the HubSpot account, or its scopes changed. Reconnect the connector.

***

### Need help?

Reach out to [Suptask Support](https://support.suptask.com/getting-started/contact-support) and our team will help you connect HubSpot.