HubSpot
The HubSpot connector reads and writes CRM records through the HubSpot CRM API. A data pipeline can pull records out of HubSpot, push records in, or keep HubSpot in step with another system.
When to use it
- You move contacts, companies and deals between HubSpot and another CRM.
- You push new customers from a database into HubSpot, or pull won deals into a warehouse for reporting.
- You read records, transform them, and write the results back with Update or Upsert.
What you need
- For an access token: a HubSpot account with access to account settings, and a private app access token or a service key.
- For OAuth: a HubSpot developer account with an app, its client ID and client secret.
- The scopes for the objects the data pipeline reads or writes.
Set up in HubSpot
Access token. A private app access token or a service key both work. HubSpot accepts either as a bearer token.
- In HubSpot, create a private app and grant it the scopes listed below. See HubSpot's private apps guide.
- Copy the access token. HubSpot shows it once.
- Paste it into Access Token.
A private app token changes when you change its scopes. Paste the new token with Replace.
OAuth.
- In your HubSpot developer account, create an app. See HubSpot's app guide. The app's Auth tab holds the client ID and client secret.
- Copy the Redirect URI from the DataLug connection form into the app's Auth tab as a redirect URL. HubSpot compares the two exactly.
- Set the app's scopes to match the Scopes field. See HubSpot's OAuth guide.
- Save the connection, click Connect HubSpot and approve access. The refresh token is filled in.
Scopes
The Scopes field is pre-filled with:
crm.objects.contacts.read, crm.objects.contacts.write, crm.objects.companies.read,
crm.objects.companies.write, crm.objects.deals.read, crm.objects.deals.write,
crm.objects.line_items.read, crm.objects.line_items.write, tickets
HubSpot rejects an authorization request that names a scope the app does not hold. Trim the field to match the app.
Connect
The connection form lists its steps on the left. Open any step from that list. The Environments step holds the values that differ per environment.
Test connection is in the form footer. Beside it, Test against picks Base, the connection as saved, or an environment, whose values are applied first.
| Field | Step | What to enter |
|---|---|---|
| Auth Type | Authentication | Access Token for one HubSpot account. OAuth for an app you distribute. |
| Access Token | Authentication | A private app access token or a service key. Access Token only. |
| Client ID | Authentication | From the app's Auth tab. OAuth only. |
| Client Secret | Authentication | From the same tab. OAuth only. |
| Redirect URI | Authentication | Filled in. Copy it into the app's Auth tab. OAuth only. |
| Scopes | Authentication | Space separated. OAuth only. |
| Refresh Token | Authentication | Filled in by Connect HubSpot. OAuth only. |
| Portal ID | Connection | Optional. Test connection fills it in and names the portal it reached. |
Stored secrets are never sent back to the browser. To change one, use Replace.
Supported operations
Objects. Contact, Company, Deal, Ticket, Line Item, Note and Task.
| Action | Node | Operations |
|---|---|---|
| Query (Source) | Source node | Query, with the fields you select and an optional Limit |
| Load (Target) | Load node | Insert, Update, Upsert, Delete |
- Update and Delete read the HubSpot record id from an input column.
Id source column defaults to
id. - Upsert matches on the Match Field you choose under Operation Details. Pick a property that holds unique values.
- Write Mode is Single record or Batch. Single record reports each
row separately. Batch uses HubSpot's batch endpoints. When HubSpot rejects a
whole batch, every row in it carries the reason in
dl_error. - Delete archives the record, which is HubSpot's delete behaviour.
- Lead status is a property on a contact.
Not supported: a Lead object, a source filter, hard delete.
Limits
HubSpot limits requests per account, and the limit depends on the
subscription. Free and Starter accounts allow 100 requests per 10 seconds and
250,000 per day. Higher tiers and the API limit increase allow more. HubSpot
reports the current figures in the X-HubSpot-RateLimit response headers.
See HubSpot's
usage guidelines.
The API limits card has no default throttle for HubSpot. Page size is at most 100.
The API limits card on the connection form is collapsed by default. Every field on it is optional, and a blank field uses the default shown below it.
| Setting | What it does | Default |
|---|---|---|
| Requests per period, Period | Paces outgoing calls. Set both to throttle. | No throttle, or the rate shown on the card. |
| Page size | Rows per request. A larger value is reduced to the provider's maximum. | The maximum shown on the card, or set by the provider. |
| Max attempts | Tries per call, including the first. | 3 |
| Cool-off (ms) | The first wait after a 429. Later waits grow from it. | 500 ms |
| Requests at once | Requests open at the same time within one run. | No limit |
A Retry-After header from the provider overrides the cool-off. The pace
applies per connection and is shared by every run on it. See
Run performance.
DataLug retries a call that the provider refused with 429, and a call that
could not connect. A read is also retried after a 408, a 5xx or a dropped
connection. A write is retried only after a 429 or a failed connection.
A Retry-After delay of up to one minute is honoured. A longer one fails the
call with the 429.
Troubleshooting
| What you see | What it means | What to try |
|---|---|---|
401 on test or on a run | The token is wrong, was rotated, or the private app was deleted. | Open the connection, click Replace on the token and paste a current one. |
401 with a key that works elsewhere | A legacy hapikey API key is not a bearer token. HubSpot retired that scheme. | Use a private app access token or a service key. |
403 with a scope name | The app does not hold the scope that object needs. | Add the scope to the app, then reconnect. A private app token changes after a scope change. HubSpot's error names internal scopes: tickets-read or tickets-access is the Tickets scope, and deal-line-item-read is Line items. Search the scope picker for the object. |
Some objects load their fields and others return 403 | A private app is scoped per object. | Grant the scopes for the objects the data pipeline uses. |
429 partway through a run | HubSpot rate-limited the account. | The run waits and retries. If every run hits it, stagger schedules or set Requests per period. |
Select a match field for Upsert. when saving the action | Upsert has no Match Field. | Pick one under Operation Details. |
| A field is missing from the picker | The field list was loaded before the property existed, or the app lacks the read scope. | Click Get Fields. If the field is still absent, check the app's scopes. |
Related
- Source node and Load node.
- Connections for environments and sharing.
- Salesforce for a migration between the two CRMs.