> For the complete documentation index, see [llms.txt](https://ask.birdie.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ask.birdie.ai/integrations-and-data-ingestion/how-to-integrate-with/hubspot.md).

# HubSpot

### Overview

Birdie's HubSpot connector imports your HubSpot data into Birdie so you can analyze it alongside your other feedback sources. It supports two kinds of data:

* **Support tickets** — imported as conversations, with the ticket's emails and notes as the messages.
* **Feedback submissions** (survey responses such as NPS, CSAT, and CES) — imported as individual feedback.

Once a day, Birdie fetches the records that were modified in HubSpot since the previous run.

### Requirements

To authenticate, Birdie uses a HubSpot **Private App access token**. You create a private app in your HubSpot account and grant it read scopes for the data you want to import:

* **Tickets:** `tickets` (read), `sales-email-read`, and `crm.objects.notes.read`
* **Feedback / survey submissions:** `crm.objects.feedback_submission.read`

Grant only the scopes for the data types you intend to import.

### Setup in HubSpot

{% stepper %}
{% step %}

### Open Private Apps

In your HubSpot account, open **Settings** (gear icon, top right) → **Integrations** → **Private Apps**.
{% endstep %}

{% step %}

### Create a private app

Click **Create a private app**, then give it a name (e.g. "Birdie integration") and a description.
{% endstep %}

{% step %}

### Configure scopes

Open the **Scopes** tab and enable the read scopes for the data you'll import (see **Requirements** above).
{% endstep %}

{% step %}

### Create the app and copy the token

Click **Create app**. HubSpot displays the **access token only once** — copy it and store it securely.
{% endstep %}
{% endstepper %}

### Share Connection Details with Birdie

Securely provide Birdie with the following:

```json
{
  "connection_details": {
    "entity": "tickets",
    "auth": {
      "method": "private_app",
      "access_token": "your-hubspot-private-app-token"
    }
  }
}
```

| Section                   | Field          | Required | Description                                                                     |
| ------------------------- | -------------- | -------- | ------------------------------------------------------------------------------- |
| `connection_details`      | `entity`       | Yes      | The data type to import: `tickets` or `surveys`. Use one connection per entity. |
| `connection_details.auth` | `method`       | Yes      | Authentication method, currently only `private_app`.                            |
| `connection_details.auth` | `access_token` | Yes      | The private app access token (shown only once when the app is created).         |

To import **both** tickets and feedback submissions, set up **two connections** — one per `entity`.

[Share credentials securely](https://ask.birdie.ai/integrations-and-data-ingestion/securely-sharing-credentials-for-data-integration) with the Birdie team. Never send credentials via email or unencrypted channels.

### Data in scope

#### Tickets (imported as conversations)

Each HubSpot ticket is imported as a conversation. The ticket's associated **emails** and **notes** are imported as the conversation's messages, and the direction of each email (incoming vs. outgoing) is preserved. Requires the `tickets`, `sales-email-read`, and `crm.objects.notes.read` scopes.

#### Feedback submissions (imported as feedback)

HubSpot **feedback submissions** (survey responses such as NPS, CSAT, and CES) are imported as individual feedback records. Requires the `crm.objects.feedback_submission.read` scope.

#### Import frequency

Birdie imports once a day, fetching only the records whose **Last Modified** date changed since the previous run — so updates are captured without re-importing everything.

#### Custom fields

Birdie can import your HubSpot **custom properties** on tickets and feedback submissions. To bring a custom property into Birdie, configure a matching custom field in the Birdie App **before** the connection is set up: the field's matching column name must equal the HubSpot property name (you can give the field any label you like inside Birdie).

### References

* HubSpot Private Apps: <https://developers.hubspot.com/docs/api/private-apps>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ask.birdie.ai/integrations-and-data-ingestion/how-to-integrate-with/hubspot.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.