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 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.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.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.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.
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.
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.
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. |
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.
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.comover TLS 1.2 or higher. The bearer token is sent in theAuthorizationheader.
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
"Invalid token" or "401 Unauthorized" when saving the integration in Circuit
"Invalid token" or "401 Unauthorized" when saving the integration in Circuit
The form picker is empty
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.New submissions are missing from the index
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.
HubSpot sends a token rotation reminder
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.
"This account does not have access to private apps"
"This account does not have access to private apps"
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.
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, Forms API