Setting Up HubSpot Integration

This guide walks you through connecting your HubSpot account to Triggr. It takes about five minutes.

Overview

The HubSpot integration lets Triggr work with your CRM data, including:

• Matching your Triggr clients to HubSpot companies
• Looking up and searching companies
• Creating, reading, updating and searching CRM records (contacts, companies, deals and custom objects) from workflows

Triggr connects using a HubSpot service key: a credential you create in HubSpot that gives API access to exactly the data you choose. You can edit, rotate or delete it at any time.

Note: Service keys are HubSpot's recommended way to connect tools like Triggr, and are currently in public beta. If your account doesn't have them yet, use a private app access token instead. Triggr works the same way with either.

Prerequisites

Before you begin, make sure you have:

• Super Admin access in HubSpot, or the Developer tools access permission
• Access to companies in HubSpot yourself. A key can only be given scopes that the person creating it already has.
• Admin access to Triggr

Step 1: Create a Service Key in HubSpot

1. In HubSpot, go to Development in the main navigation
2. In the left sidebar, go to Keys > Service keys
   • You can also find this under Settings > Integrations > Service Keys.
3. Click Create service key in the top right
4. Enter a name, such as Triggr

Step 2: Choose the Scopes

Scopes control what Triggr can see and change in HubSpot. Click Add new scope, search for and tick each scope below, then click Update.

Required

Scope	Why Triggr needs it
crm.objects.companies.read	Map your Triggr clients to HubSpot companies, and look up and search companies

Optional: add only the ones your workflows need

Scope	Enables
crm.objects.companies.write	Creating and updating companies
crm.objects.contacts.read	Reading and searching contacts
crm.objects.contacts.write	Creating, updating and deleting contacts
crm.objects.deals.read	Reading and searching deals
crm.objects.deals.write	Creating, updating and deleting deals
crm.objects.custom.read	Reading and searching custom objects
crm.objects.custom.write	Creating, updating and deleting custom objects

Tip: Start with the required scope plus the read scopes you expect to use. You can add scopes later without reconnecting Triggr.

Custom objects: when a workflow works with a custom object, it refers to the object by its ID (for example 2-3465404). Find it in HubSpot under Settings > Objects > Custom Objects.

Step 3: Create the Key and Copy It

1. Review the scopes, then click Create and confirm
2. On the key's details page, click Show, then Copy

The key starts with pat- (for example, pat-na1-… or pat-eu1-…).

Important: Treat this key like a password. Anyone who has it can access your HubSpot data within the scopes you selected. Paste it straight into Triggr and don't share it by email or chat.

Step 4: Configure in Triggr

1. In Triggr, navigate to Integrations
2. Find and select HubSpot
3. Click + Configure to the right of the Base Configuration card
4. In the API Key field, paste the key from Step 3
5. Click Save Configuration

Step 5: Map Your Clients to HubSpot Companies

Once the integration is connected, link each Triggr client to its company in HubSpot. Workflows use this link to find the right HubSpot records for each client.

1. On the HubSpot integration page in Triggr, scroll to the Client Mapping card
2. Each Triggr client is listed with a Suggested HubSpot company, matched by name, and a match percentage
3. To accept every 100% match at once, click Apply 100% Matches, then Apply Matches to confirm
4. For other suggestions, click Apply next to any that are correct
5. For any client without the right suggestion, use the Mapped to dropdown to search for and select its HubSpot company

Each client's HubSpot company ID is saved as the client's hubspotId variable, ready for use in workflows.

Note: Suggestions compare client names with the company Name in HubSpot, ignoring case and punctuation. If a client has no suggestion, search for the company in the Mapped to dropdown instead.

Rotating or Removing the Key

You can manage the key at any time from its details page in HubSpot (Development > Keys > Service keys).

• To rotate: click Rotate, then paste the new key into the API Key field in Triggr (Step 4).
  • Rotate and expire later keeps the old key working for 7 days, so nothing breaks while you update Triggr.
  • Rotate and expire now stops the old key immediately. Use this if the key may have been exposed.
• To see what Triggr is doing: click View logs for the key's recent requests.
• To disconnect Triggr: delete the key in HubSpot, or click Unlink on the Base Configuration card in Triggr.

Alternative: Private App Access Token

If your HubSpot account doesn't have service keys yet, create a private app instead. Triggr uses its access token in exactly the same way.

1. In HubSpot, click the Settings icon (the gear), then go to Development > Legacy apps
2. Click Create legacy app, choose Private, and name it Triggr
   • In older HubSpot accounts, go to Integrations > Private Apps and click Create a private app instead.
3. On the Scopes tab, add the scopes from Step 2
4. Click Create app, then Continue creating
5. On the app's Auth tab, click Show token, then Copy
6. Continue from Step 4

To change scopes later, open the app, click Edit app, update the Scopes tab and click Commit changes. The token stays the same. To rotate the token, use Rotate on the Auth tab and update the API Key in Triggr.

Troubleshooting

Authentication Errors (401)

1. Check the key was pasted in full, with no spaces before or after it
2. Check the key hasn't been rotated, expired or deleted in HubSpot
3. Paste a fresh copy of the key into Triggr and save

Permission Errors (403 or "MISSING_SCOPES")

The key doesn't have a scope that the action needs.

1. In HubSpot, open the Triggr key and click Edit
2. Add the missing scope (see Step 2) and save
3. Retry the action in Triggr

Companies Missing from Client Mapping

1. Check the key has the crm.objects.companies.read scope
2. Check the companies have a Name in HubSpot
3. Click Refresh on the Client Mapping card in Triggr to reload the HubSpot company list

Rate Limits (429)

HubSpot limits how many API requests a key can make in a short period. If very large bulk workflows hit rate-limit errors, spread the work out over time or run it in smaller batches.

---

Need help? Contact your account manager. We're happy to help configure this integration with you.