HubSpot Integration Guide
The Topiq HubSpot integration keeps your deals, companies and contacts in step between Topiq and your HubSpot portal. You connect it once, with a service key made in your own HubSpot account. This guide covers how to add, use and remove the integration.
A service key works like a spare house key: it opens only the parts of HubSpot you choose, and you can take it back at any time.
Before you start
- You need a Topiq account. Topiq is available at app.topiq.work.
- You need to be a Super Admin in your HubSpot account to create a service key.
- Connecting HubSpot is done once for the whole workspace, by a Topiq owner or admin. If that isn't you, you can create the key and send it to your Topiq admin.
1. Adding the HubSpot integration
Step 1: Open the service keys page in HubSpot
- Sign in to HubSpot and open Development in the main menu.
- In the left sidebar, go to Keys → Service keys.
- If you don't see Development, look under Settings → Integrations.
Step 2: Create a key for Topiq
- Click Create service key and name it Topiq, so you'll recognise it later.
Step 3: Choose what Topiq can see and change
Use Add new scope to add each of these:
| Scope | Access | Why Topiq needs it |
|---|---|---|
| crm.objects.contacts | Read and write | Keeps your people in sync |
| crm.objects.companies | Read and write | Keeps your companies in sync |
| crm.objects.deals | Read and write | Keeps your deals in sync |
| crm.schemas.contacts, crm.schemas.companies, crm.schemas.deals | Read and write | Reads your custom fields, and adds a "Topiq ID" field so records always match up |
| crm.objects.owners | Read | Shows the right person as a deal's owner |
| tickets (optional) | Read and write | Only needed if you want Topiq to file or read HubSpot tickets |
Step 4: Create and copy the key
- Click Create. HubSpot shows a long code that starts with pat-. That is the key. Copy it.
- Treat the key like a password. Don't paste it into email or chat. If you are handing it to a colleague, use a password manager's secure share.
Step 5: Paste the key into Topiq
- In Topiq, open Integrations and find the HubSpot card.
- Paste the key and click Save changes.
An existing HubSpot private app token also works in the same box. HubSpot no longer lets you create new private apps, so new connections use a service key.
2. Using the HubSpot integration
What syncs
- Deals sync both ways from the moment you connect.
- New companies and contacts you add in Topiq are created in HubSpot automatically. Companies are matched by website and contacts by email, so a record HubSpot already has is linked rather than duplicated.
- Edits to companies and contacts in HubSpot come into Topiq only once you turn that on. Your Topiq admin controls this, and the ticket options, on the HubSpot mappings page. All of them start switched off.
Before you rely on deal sync
- On the HubSpot mappings page, match each Topiq deal stage to the stage it belongs to in your HubSpot pipeline, and check the field mappings.
What Topiq accesses
- Only the objects and scopes you granted in Step 3. Topiq can't reach anything else in your HubSpot account, such as marketing emails, files or settings.
3. Removing the HubSpot integration
Delete the key
- Open Development → Keys → Service keys in HubSpot and delete the Topiq key. Topiq's access stops immediately.
- If you'd also like the key cleared from your Topiq workspace, email support@topiq.work.
What happens after removal
- Nothing more is sent to or read from HubSpot.
- Records already synced stay where they are, in both Topiq and HubSpot.
- To reconnect, follow the steps in Adding the HubSpot integration again.
4. Troubleshooting
- Topiq says the key was rejected. The key was deleted in HubSpot, or copied incompletely. Create a new key and paste it again.
- A feature says a permission is missing. The key is missing a scope from Step 3. Add the scope to the key in HubSpot; you don't need a new key.
- A company or contact didn't reach HubSpot. Topiq needs a website for a company and an email or LinkedIn profile for a contact to match it safely. The record's page in Topiq shows when one is missing.
Support
For help with the HubSpot integration, email support@topiq.work. Our team is available Monday through Friday, 9:00 AM – 5:00 PM PT, excluding major U.S. holidays, and responds within 3 business days.