HubSpot
Create or update HubSpot records from Encatch survey responses - where to create the service key in HubSpot and how to map fields
Overview
The HubSpot connector writes survey responses to HubSpot as records: contacts, companies, deals, tickets or a custom object. Each submitted response creates a record or updates the one it matches.
Encatch connects with a service key that you create in your own HubSpot account. You choose what the key can reach, you can see every call it makes, and you can turn it off at any time.
| What it gets | A record created or updated from each response |
| Events | Survey submitted, and Survey partially submitted when ticked |
| Anonymous respondents | Not sent: identified users only |
| Test connection | Checks the key only: nothing is written in HubSpot |
| Status | Available |
What You'll Need
Before you start, make sure you have:
- A HubSpot account — every HubSpot plan works, Free CRM included
- The right permission in HubSpot — a Super Admin, or a user with the Developer tools access permission. A key can only get scopes that its creator has
- About 5 minutes
Step 1: Create the service key in HubSpot
- In HubSpot, click the Settings icon (top right).
- In the left menu, open Integrations → Service Keys. In some accounts it is under Development → Keys → Service Keys.
- Click Create service key.
- Name: something you'll recognise, for example
Encatch. It shows in HubSpot's logs. - Under Scopes, click Add new scope and tick the scopes for the object Encatch will write:
| Object Encatch writes | Scopes |
|---|---|
| Contacts | crm.objects.contacts.read, crm.objects.contacts.write, crm.schemas.contacts.read |
| Companies | crm.objects.companies.read, crm.objects.companies.write, crm.schemas.companies.read |
| Deals, tickets or a custom object | That object's read, write and schemas … read scopes |
- Click Update, then Create, and confirm.
Tick only what you need. You can add scopes to the key later with Edit on the key's page.
Step 2: Copy the key
- On the key's page, under Service Key, click Copy. The key starts with
pat-followed by your data region, for examplepat-na1-orpat-eu1-. - Keep it somewhere safe until you paste it. Anyone with the key can reach the data its scopes allow.
Step 3: Add the connection in Encatch
- In Encatch, open Data sync → Survey events and click Add connection.
- Choose HubSpot and enter a Name.
- Paste the key into Service key.
- Click Load from HubSpot. Encatch reads your account details, your objects and the fields of the object you choose, without changing anything. It shows Connected to HubSpot account … so you can check it's the right one.
- Fill in the record settings:
| Field | What to enter |
|---|---|
| Object | The record type Encatch creates or updates, for example contacts. |
| Find the record | Find by a field, create if none (default), Update by the record ID held in a trait, or Always create a new record. |
| Field that finds the record | The HubSpot property to match on, for example email, and the Encatch value to compare it with. |
| Fallback field | Optional. A second way to find the record, for example a unique property holding the Encatch user ID. |
| Field mapping | One row per HubSpot property: the property, and the Encatch value written to it. |
Values you can map: an answer to a question, the score (first NPS or rating answer), the survey name, the response ID, the submitted time, the response status, the user ID and any user trait.
- Press Test connection. It checks the service key by reading your HubSpot account and the properties of the object you chose.
If you find records by email, add a fallback. A response with no email is then matched by the fallback. With no value for either, nothing is written and the event shows as Skipped in Logs: no record is created without a key.
Step 4: Save and start sending
Pick the surveys, click Save, then press Start sending. Saving checks the key and the mapping again. Each submitted survey then writes a record, and Logs show what HubSpot answered.
Other options (partial responses, rate limit, Admin API responses) are explained in Connection settings.
Check it in HubSpot
- Open the object you mapped (for example Contacts) and find the record the response created or updated.
- View Logs on the key's page lists every call Encatch makes with the key.
Rotating or replacing the key
- Rotate on the key's page in HubSpot makes a new key. Choose Rotate and expire this key later to keep the old key working for 7 days, then paste the new key into Encatch with Replace within those 7 days.
- Automatic Rotation (off by default) rotates every 3, 6 or 12 months with the same 7-day overlap. If you turn it on, set a reminder to paste each new key.
- Deleting the key stops Encatch at once. The connection then shows that HubSpot refused the key.
Good to know
- API limits. Encatch's calls count against your account's daily API limit, shared with your other integrations. On Free and Starter that is 250,000 calls a day and 100 every 10 seconds. One response is one call, or two when the record is found first.
- Rate limit. A new connection starts at 150 a minute. HubSpot takes 100 requests per 10 seconds per app on Free and Starter (190 on Professional and Enterprise) and 5 searches a second per account. The rate limit cannot protect the daily allowance.
- Service keys are a beta feature in HubSpot. They replace private apps, which HubSpot no longer lets you create. If you already have a private app with the scopes above, its access token (also
pat-…) works in the same field. - Encatch only uses the key from its servers; it is never sent to your users' browsers.
Troubleshooting
| What Encatch shows | What it means | What to do |
|---|---|---|
| HubSpot refused the service key | The key was deleted, rotated past its 7 days, or mistyped | Copy the current key from HubSpot and paste it with Replace |
| HubSpot needs more access: scope names | The key is missing a scope for what you mapped | On the key's page, Edit → Add new scope, tick the scopes named, save. If HubSpot shows a new key value, paste it with Replace |
| HubSpot's rate limit was reached | The account's daily or 10-second limit is used up | Encatch retries later; if it keeps happening, check other integrations' use in HubSpot |
| Field isn't writable | A mapped property is read-only or calculated in HubSpot | Map a different property |
Was this page helpful?
