---
title: HubSpot connector
description: Use the HubSpot connector to search and retrieve contacts, companies, deals, tickets, and engagements from HubSpot CRM.
url: https://docs-v3-preview.elastic.dev/elastic/kibana/pull/303145/reference/connectors-kibana/hubspot-action-type
products:
- Kibana
applies_to:
- Elastic Cloud Serverless: Preview
- Elastic Stack: Preview since 9.4
---
# HubSpot connector
The HubSpot connector communicates with the HubSpot CRM API to search and retrieve contacts, companies, deals, tickets, and engagements from your HubSpot account.
You can use this connector in **Agent Builder** and **Workflows**.
## Create connectors in Kibana
You can create connectors in **Stack Management > Connectors**.
### Connector configuration
HubSpot connectors support two authentication methods:
Authenticates using a static token. Use a **Service Key** (recommended) from HubSpot Development, or a **Private App** access token (starts with `pat-`). See [Get API credentials](#hubspot-api-credentials) for both options.
- **Private App Access Token**: The HubSpot access token.
Authenticates via the OAuth 2.0 authorization code flow using a HubSpot Public App. Requires a **Client ID** and **Client Secret** from a HubSpot Public App. The authorization and token URLs are pre-filled; adjust the **Scopes** field if you need access beyond the defaults. See [OAuth (Public App)](#hubspot-oauth-public-app) for setup instructions.
## Test connectors
You can test connectors while creating or editing them in Kibana.
The HubSpot connector has the following actions:
Search or list one HubSpot CRM object type. Omit **Query** to page through records.
- **Object Type** (required): `contacts`, `companies`, `deals`, `tickets`, or an engagement type: `calls`, `emails`, `meetings`, `notes`, or `tasks`.
- **Query** (optional): Keyword for search; omit to list records (with pagination).
- **Properties** (optional): Property names to return (where supported).
- **Limit** (optional): Maximum number of results to return (default: 10).
- **Include Associated Deals** (optional): For `contacts` only—also returns linked deal IDs.
Retrieve the full details of a specific CRM record by its ID.
- **Object Type** (required): Same values as **Search CRM Objects** (`contacts`, `companies`, `deals`, `tickets`, `calls`, `emails`, `meetings`, `notes`, or `tasks`).
- **Object ID** (required): The unique HubSpot object ID of the record.
- **Properties** (optional): Comma-separated list of property names to include in the response.
Search HubSpot deals with optional keyword, owner, pipeline, and stage filters.
- **Query** (optional): Keyword to search for in deal names or properties.
- **Owner ID** (optional): HubSpot owner ID (`hubspot_owner_id`) to filter deals by. Use the **List Owners** action to resolve an owner name to their ID.
- **Pipeline** (optional): The HubSpot pipeline ID to filter deals by (for example, `default`). Use the **List Pipelines** action to discover valid pipeline IDs.
- **Deal Stage** (optional): The deal stage ID to filter by (for example, `closedwon`, `closedlost`). Use the **List Pipelines** action to discover valid stage IDs.
- **Limit** (optional): Maximum number of results to return (default: 10).
Run a single keyword search across contacts, companies, deals, and tickets simultaneously. Returns results grouped by object type.
- **Query** (required): Keyword or phrase to search across all four object types in parallel.
- **Limit** (optional): Maximum number of results per object type (default: 5).
List HubSpot owners (users with CRM access) to discover who is assigned to contacts, companies, or deals.
- **Limit** (optional): Maximum number of owners to return (default: 20).
List HubSpot pipelines and their stages for deals or tickets. Use this to discover valid pipeline IDs and deal stage IDs before filtering with **Search Deals**.
- **Object Type** (optional): The CRM object type to list pipelines for (`deals` or `tickets`). Defaults to `deals`.
## Connector networking configuration
Use the [Action configuration settings](/elastic/kibana/pull/303145/reference/configuration-reference/alerting-settings#action-settings) to customize connector networking configurations, such as proxies, certificates, or TLS settings. You can set configurations that apply to all your connectors or use `xpack.actions.customHostSettings` to set per-host configurations.
## Get API credentials
The connector supports three credential types: a Service Key (recommended for token auth), a Private App access token (legacy token auth), or OAuth via a Public App. Use a Service Key or OAuth when possible.
### Service Key (recommended)
Service Keys are managed under **Development** in HubSpot and can call the same CRM APIs with the scopes you assign.
1. Log in to your [HubSpot account](https://app.hubspot.com/).
2. In the main navigation, go to **Development**, then **Keys** (or **Settings → Development → Keys**).
3. Create a new key or select an existing one, and choose **Service Key** (or the equivalent key type that supports CRM scopes).
4. Under **Scopes**, grant at least the following (minimum for connector actions such as Search CRM Objects, Get CRM Object, List Owners, Search Deals, List Pipelines):
- `crm.objects.contacts.read`
- `crm.objects.companies.read`
- `crm.objects.deals.read`
- `tickets`
- `crm.objects.owners.read`
5. If you use **List Pipelines**, also add (if available):
- `crm.schemas.companies.read`
- `crm.schemas.contacts.read`
- `crm.schemas.deals.read`
6. Save the key and copy the generated token (it can start with `pat-` or another prefix).
7. Use this value as the **Private App Access Token** when configuring the HubSpot connector in Kibana.
### Private App (legacy)
Creating a Private App (app integration) is the **legacy** way to obtain a token. Use this option if you need engagement read scopes (notes, calls, emails, meetings, tasks via **Search CRM Objects**), or if Service Keys are not available for your account. HubSpot may restrict or remove the ability to create new Private Apps in some accounts.
1. Log in to your [HubSpot account](https://app.hubspot.com/).
2. Select the **Settings** icon in the top navigation bar.
3. In the left sidebar, select **Integrations → Private Apps**.
4. Select **Create a private app**.
5. On the **Basic Info** tab, give your app a name (for example, "Elastic Agent Builder").
6. Go to the **Scopes** tab and add at least:
- `crm.objects.contacts.read`
- `crm.objects.companies.read`
- `crm.objects.deals.read`
- `tickets`
- `crm.objects.owners.read`
For engagement types in **Search CRM Objects**, also add scopes such as `sales-email-read` (emails) and any engagement read scopes your account offers for notes, calls, and meetings.
7. Select **Create app** and confirm by selecting **Continue Creating**.
8. On the confirmation dialog, copy the **Access Token** (starts with `pat-`).
9. Use this token as the **Private App Access Token** when configuring the connector in Kibana.
### OAuth (Public App)
OAuth uses the authorization code flow with a HubSpot Public App. Unlike Private Apps, Public Apps are registered in a HubSpot developer account and support OAuth on behalf of any HubSpot portal.
1. Log in to your [HubSpot developer account](https://developers.hubspot.com/).
2. Select **Apps** in the top navigation, then select **Create app** (or open an existing app).
3. On the **App Info** tab, give your app a name (for example, "Elastic Agent Builder").
4. On the **Auth** tab, under **Redirect URLs**, add your Kibana OAuth callback URL:
`https:///api/actions/connector/_oauth_callback`
5. Under **Scopes**, add at least:
- `crm.objects.contacts.read`
- `crm.objects.companies.read`
- `crm.objects.deals.read`
- `tickets`
- `crm.objects.owners.read`
6. Save the app. On the **Auth** tab, copy the **Client ID** and **Client Secret**.
7. In Kibana, create a HubSpot connector and select **OAuth** as the authentication type. Enter the **Client ID** and **Client Secret**. Adjust the **Scopes** field if needed, then complete the OAuth authorization flow.
Keep your access token secure. Anyone with this token can access your HubSpot CRM data.