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

# HubSpot Forms

> Sync HubSpot form submissions into a Circuit index as documents.

The HubSpot Forms feed connects an index to HubSpot's forms API. Each submission becomes a document in the index, so agents can search and reference form responses alongside the rest of your knowledge.

This is the HubSpot **Forms** feed. It is separate from the HubSpot transactional email agent tool, which lets an agent send mail from HubSpot. See [HubSpot (agent tool)](/admin/integrations/agent-tools/hubspot) for that integration.

## What you can do

* **Index form submissions**: Bring every submission to the forms you choose into a Circuit index. Each submission is one document, with the field values searchable as text.
* **Cover marketing and growth forms**: Any form built in HubSpot Marketing is eligible, including embedded forms, pop-up forms, and standalone landing-page forms.
* **Stay in sync automatically**: Circuit re-checks HubSpot periodically. New submissions appear in the index without manual work.

## Before you start

* A HubSpot account on a tier that exposes the forms API.
* A HubSpot user with **Super Admin** access. HubSpot restricts private app creation to super admins.
* An index in Circuit where the submissions should live. See [Indexes](/admin/indexes) if you need to create one.

## Connect HubSpot Forms

The HubSpot Forms integration uses a HubSpot **private app access token** that you create in HubSpot and paste into Circuit. HubSpot deprecated legacy API keys in 2022; private apps are the supported path.

<Steps>
  <Step title="Create a private app in HubSpot">
    In HubSpot, open **Settings** (gear icon) > **Integrations** > **Private Apps** and click **Create a private app**. Give it a recognizable name, for example `Circuit Forms`, and optionally add a description and logo.
  </Step>

  <Step title="Grant the forms read scope">
    Open the **Scopes** tab. Search for `forms` and select the **Read** checkbox for the **forms** scope. This is the only scope Circuit needs for this integration.
  </Step>

  <Step title="Create the app and copy the access token">
    Click **Create app** in the upper right. HubSpot shows a one-time prompt to view the access token. Open the **Auth** tab, click **Show token**, and copy the token. Treat the token like a password.
  </Step>

  <Step title="Open the HubSpot Forms integration in Circuit">
    In Circuit, open the index that should receive the submissions, choose **Integrations** > **New integration**, and select **Import from HubSpot Forms**.
  </Step>

  <Step title="Paste the token and select forms">
    Paste the private app access token into Circuit. Circuit verifies the token and lists the forms available in the connected HubSpot account. Select the forms whose submissions you want to import.
  </Step>

  <Step title="Start the import">
    Click **Done**. Circuit imports past submissions for the selected forms and continues syncing new submissions on a regular cadence.
  </Step>
</Steps>

## What Circuit accesses

| Scope          | Why Circuit needs it                                                                                                 |
| -------------- | -------------------------------------------------------------------------------------------------------------------- |
| `forms` (Read) | List the forms in your HubSpot account and read their submissions so Circuit can import field values into the index. |

Circuit does not request any other HubSpot scopes through this integration. The token cannot read contacts, deals, conversations, or other HubSpot objects.

<Note>
  The token Circuit stores is a HubSpot private app access token. It is bound to the HubSpot account it was created in and the scopes selected at creation time. Reducing the scopes in HubSpot reduces what Circuit can see immediately.
</Note>

## For IT and security teams

The HubSpot Forms integration uses a static bearer token (HubSpot private app access token), not OAuth. The security model differs from Circuit's OAuth-based integrations in a few important ways:

* **Token creation is admin-gated**: HubSpot allows only super admins to create private apps. This puts a natural gate on who can establish the connection.
* **Scope locking**: The token's permissions are fixed at creation. Circuit cannot request additional scopes later without you rotating the token. Keep the scope set to `forms` (Read) unless your use case changes.
* **Rotation**: HubSpot recommends rotating private app tokens every six months and sends reminders to super admins. To rotate, open the app's **Auth** tab in HubSpot and click **Rotate**. Update the token in Circuit's HubSpot Forms feed settings before the previous token expires.
* **Revocation**: Deleting the private app in HubSpot revokes the token immediately. Circuit will stop syncing on the next attempt.
* **Audit**: HubSpot logs private app API calls under **Settings** > **Integrations** > **Private Apps** > the app > **Logs**.
* **Network**: All calls go to `api.hubapi.com` over TLS 1.2 or higher. The bearer token is sent in the `Authorization` header.

See [Integration security and admin consent](/it/integration-security) for credential handling across Circuit integrations.

## Disconnect or rotate access

* **From Circuit**: open the index's **Integrations** tab, select the HubSpot Forms feed, and click **Remove**. Circuit deletes the stored token and stops syncing. Already-imported documents stay in the index until you delete them.
* **Rotate the token**: in HubSpot, open the private app, go to **Auth**, and click **Rotate**. Choose **Rotate and expire later** for a grace window, then paste the new token into Circuit's feed settings before the old token expires.
* **From HubSpot (revoke completely)**: open the private app in HubSpot and delete it. The token stops working immediately.

## Troubleshooting

<AccordionGroup>
  <Accordion title="&#x22;Invalid token&#x22; or &#x22;401 Unauthorized&#x22; when saving the integration in Circuit">
    The token was not copied completely, or the private app has been deleted in HubSpot. Recreate the token by opening the app's **Auth** tab in HubSpot, clicking **Show token**, and pasting it freshly into Circuit.
  </Accordion>

  <Accordion title="The form picker is empty">
    The `forms` scope was not granted Read access when the private app was created, or no forms exist in the connected HubSpot account. Reopen the private app in HubSpot, check the **Scopes** tab for **forms** with the Read box selected, and confirm that forms exist under **Marketing** > **Lead Capture** > **Forms**.
  </Accordion>

  <Accordion title="New submissions are missing from the index">
    Submissions appear on the next sync cycle, usually within a few hours. If a submission has been in HubSpot for longer than that and is still missing, force a re-sync from the feed's settings.
  </Accordion>

  <Accordion title="HubSpot sends a token rotation reminder">
    HubSpot reminds super admins to rotate tokens every six months. Rotate in HubSpot using **Rotate and expire later**, paste the new token into Circuit, and wait for the next sync to confirm the new token works before the old one expires.
  </Accordion>

  <Accordion title="&#x22;This account does not have access to private apps&#x22;">
    The HubSpot tier does not include private apps, or the user creating the app is not a super admin. Ask a super admin in the HubSpot account to create the app on your behalf.
  </Accordion>
</AccordionGroup>

## Reference

* **Authentication**: HubSpot private app access token (bearer)
* **Scopes requested**: `forms` (Read)
* **API endpoint**: `https://api.hubapi.com`
* **HubSpot's own docs**: [Private apps overview](https://developers.hubspot.com/docs/api/private-apps), [Forms API](https://developers.hubspot.com/docs/api/marketing/forms)