1. Overview
The Ana x HubSpot integration connects your HubSpot CRM to Ana, giving you natural language access to your team’s deals, contacts, pipelines, and ticket data. Once configured, Ana can query deal statuses, track pipeline progress, surface at-risk opportunities, and analyze sales performance directly in Ana.
Connect HubSpot to Ana to query and analyze your team’s CRM and sales data using natural language.
2. Prerequisites
You’ll need:
- A HubSpot account you want Ana to query
- Owner or admin access to your HubSpot workspace if you are setting up an org-level integration
- A TextQL account with permission to add API connectors
Which type of connection should I use?
| API Token | OAuth (Org-level) | OAuth (Per-member) |
|---|
| Best For | Individual users, service accounts, or shared team access tied to a single user’s permissions | Shared team access to a single HubSpot portal | Individual user access with personal permissions |
| Scope | Access tied to the token owner’s permissions | Full org workspace access under one shared auth | Each user queries HubSpot as themselves |
| Authentication | API Token from HubSpot settings | One-time OAuth flow by an admin | Each member completes their own OAuth flow |
| Data Visibility | Limited to what the token owner can see | Consistent view across all Ana users | Each user sees only what they have access to in HubSpot |
3. Capabilities
Once configured, Ana can:
- Query open, active, or stalled deals across any pipeline or sales team in plain language.
- Track how many deals are in each stage and identify which ones haven’t had recent activity.
- Analyze lead sources, conversion rates, and sales performance over time.
- Get a snapshot of contact and company data, including follow-up status and engagement history.
- Surface at-risk opportunities and highlight tickets that need attention across your team.
4. Setup Instructions
Step 1: Generate your HubSpot credentials
Before you begin, choose your connection type. If you’re unsure, refer to Which type of connection should I use? Then follow the instructions below for your chosen type.
- Login to HubSpot
- Click on Settings (gear icon at the top right)
- In the left sidebar, scroll down to Integrations and click Private Apps or Personal Access Key
- Scroll down and click Generate token
- Click Show to reveal the token, then click Copy
New to the command line? The “terminal” (also called CLI, or “command line”) is an app where you type commands instead of clicking buttons. On Mac, open it by pressing Cmd + Space, typing “Terminal”, and hitting Enter. On Windows, search for “Command Prompt” or “PowerShell” in the Start menu. You’ll type each command below, then press Enter to run it. Don’t type the word bash , that’s just labeling which kind of command it is.
npm command). If you’re not sure whether you have it, type npm -v and press Enter. If you see a version number, you’re good. If you see “command not found,” install Node.js from nodejs.org first.1. Install the HubSpot CLI
A one-time install that gives you the hs command.npm install -g @hubspot/cli
2. Create the project
Run:You’ll be prompted with the following — answer as shown:| Prompt | What to enter |
|---|
| Enter your project name | Any name you like, e.g. ana-hubspot |
| Choose where to create the project | Pick a folder, or press Enter for the suggested one |
| Choose what to include in your project | App |
| Choose how to distribute your app | Privately |
| Choose your authentication type | OAuth |
| Choose which features to add | Press Enter to skip |
When it’s done, you’ll see a green SUCCESS message telling you where the project was created. Take note of that folder location — you’ll need it next.
3. Find and open the config file
You need to edit one file inside your new project. To locate it, run the command below, replacing <your-username> with your actual Mac username:find /Users/<your-username> -name "app-hsmeta.json" 2>/dev/null
/Users/<your-username>/<your-destination-folder>/src/app/app-hsmeta.json
open /Users/<your-username>/<your-destination-folder>/src/app/app-hsmeta.json
4. Edit the redirect URL
Inside the file, find the section labeled redirectUrls. Replace the existing URL (http://localhost:3000) so it looks exactly like this:"redirectUrls": [
"https://app.textql.com/auth/api-oauth/callback"
]
5. Upload the project to HubSpot
Back in the terminal, move into your project folder first. The cd command means “change directory” — it tells the terminal which folder to work in.cd /Users/<your-username>/<your-destination-folder>
Instead of typing the long folder path, type cd (with a space after it), then drag the project folder from Finder onto the terminal window — it’ll fill in the path automatically.
Yes and press Enter.You’ll see a series of SUCCESS and DONE messages as it creates, builds, and deploys the project. Once you see Deployed build #1 ... DONE, you’re finished with the terminal.6. Get your credentials
Open this link in your browser, replacing the bracketed parts with your own account ID and project name:https://app.hubspot.com/developer-projects/<your-account-id>/project/<your-project-name>
| Value | How to get it |
|---|
| Client ID | Copy it |
| Client Secret | Click Show, then copy it |
| Redirect URL | Confirm it shows https://app.textql.com/auth/api-oauth/callback |
Treat the Client Secret like a password. Don’t commit it to source control or share it in plain text — paste it only into the secure field it’s needed for.
Step 2: Add HubSpot as an API connector in TextQL
- Go to app.textql.com and sign in.
- In the bottom left sidebar, click Connectors > APIs and select HubSpot.
- In the configuration panel, fill in the fields depending on your connection type:
- API Token
- Name (e.g. HubSpot
API Token)
- Authentication type: select API Token
- Token: paste the token copied from Step 1
- OAuth (Org-level or Per-member)
- Name (e.g. HubSpot
OAuth)
- Authentication type: select OAuth (org-level) or OAuth (per-member)
- Client ID and Client Secret: paste the values copied from Step 1
- Scopes: enter
oauth crm.objects.contacts.read crm.objects.contacts.write
- Grant Type: select Authorization Code
- Token Auth Method: select POST params
- Authorization URL:
https://app.hubspot.com/oauth/authorize
- Token URL:
https://api.hubspot.com/oauth/v3/token
- Hosts:
https://api.hubapi.com:443
- OAuth Authentication: click Authenticate — a popup will appear asking for permissions to access your HubSpot account. Click Allow.
- Click Save.
Step 3: Verify the connection
Once saved, confirm the connector is active:
- Click on the HubSpot connector and select Test Connection at the bottom of the panel.
- A successful setup will return Connection successful (200).
- If the test fails, refer to the Troubleshooting section for next steps.
5. Usage Examples
Once configured, you can ask Ana:
- “Show me all deals over $50k that haven’t been updated in more than 10 days.”
- “Which deals are expected to close this quarter but have no recent activity?”
- “Find all contacts who attended a webinar but haven’t been followed up with.”
- “How many leads came from paid search vs. organic last quarter?”
- “What’s the average ticket resolution time by team this month?”
5. Troubleshooting
| Symptom | Likely Cause | Fix |
|---|
| Could not find OAuth client with clientId (OAuth) | Client ID or secret were not configured or expired | Confirm the Client ID and Client Secret were pasted correctly in Connectors → APIs → HubSpot with no extra spaces. If authentication has expired or been revoked, re-run the OAuth authentication flow in TextQL and authorize the application again. |
| Authentication failed (OAuth org-level or per-member) | Incorrect redirect URL | In your HubSpot settings, make sure https://app.textql.com/auth/api-oauth/callback is listed exactly as a redirect URL. |
cd: no such file or directory when running hs project upload | Wrong directory path | Run find /Users/<your-username> -name "app-hsmeta.json" 2>/dev/null to locate the correct folder, then cd into it before uploading. |
| Missing required parameter: scope | No scopes added | In the Scopes field in TextQL, enter: |
| `oauth | | |
| crm.objects.contacts.read crm.objects.contacts.write` | | |
7. Security Notes
- Follow the principle of least privilege when creating Private Apps or OAuth applications in HubSpot. Grant only the scopes required for Ana to query the data you need — for example, if you only need deal and contact data, do not enable scopes for billing or account settings.
- Private App tokens remain valid until they are manually revoked. Store them securely and rotate them if you suspect they have been exposed.
- OAuth access may require re-authentication if the connected user’s HubSpot account is deactivated, their role is changed, or the OAuth app’s authorization is revoked from within HubSpot.
- Do not share Private App tokens, client secrets, or OAuth credentials in email, chat, tickets, or other unsecured locations.
- If you no longer need the integration, revoke the Private App’s token or remove the OAuth app’s access under HubSpot Settings > Integrations > Private Apps, and remove the connector from TextQL.
- For more details on how HubSpot handles API authentication and token security, refer to the HubSpot Developer Documentation.
Need Help?
For further assistance, please contact support@textql.com.
Privacy Policy
For information about how we handle your data and protect your privacy, please review our Privacy Policy.
