# HubSpot — CRM API: connection

> Canonical URL: https://developers.apideck.com/apis/crm/hubspot/connection

# How to connect HubSpot

Connecting HubSpot is a single action: click **Authorize** and sign in with your HubSpot login.
There are no credentials to create, copy, or paste: no client ID, no client secret, no API key.
Apideck runs the OAuth flow for you and keeps the short-lived access token refreshed afterwards, so
the connection keeps working without you re-entering anything.

One HubSpot app and one set of scopes cover both the CRM and the Lead API (leads read and write
through HubSpot contacts, and opportunities through HubSpot deals), so there is no second HubSpot
connector to set up and no second set of credentials. Each unified API you use does get its own
connection in Vault, so if you use both the CRM and the Lead API, authorize both. The second one is
quick: the app is already installed in your HubSpot account and no new scopes are requested, so you
sign in with the same HubSpot login and confirm.

The one thing worth checking **before** you click Authorize is whether your HubSpot user is allowed
to install apps: that is the single most common reason an otherwise trivial connection fails. The
next section covers it.

## Prerequisites

- **A HubSpot account.** Any edition works, including the free CRM.
- **A HubSpot user with the App Marketplace Access permission.** HubSpot requires this permission
  whenever an install asks for scopes the account has not approved yet, which is exactly what a
  first-time connection does. **Super admins have it automatically**, so if you are a super admin
  there is nothing to do here. Otherwise, ask an account admin to grant it: see
  [New permission requirements for installing public apps](https://developers.hubspot.com/changelog/new-permission-requirements-for-installing-public-apps).
  Once the app is installed, later re-authorizations by you or a colleague do **not** need this
  permission, as long as the scopes have not changed. One exception matters: if the app is
  **uninstalled** from your HubSpot account, HubSpot treats the next install as a brand-new app with
  no granted permissions, so App Marketplace Access is needed again for that install.
- **The permissions the requested scopes imply.** The app's requirements are listed on its App
  Marketplace listing page under **Requirements → HubSpot Account permissions**. In practice the
  one most often missing is **Edit property settings**, which a user needs if the integration
  creates or updates HubSpot properties (custom fields).
- **The right HubSpot account in mind.** A connection is anchored to the single HubSpot account you
  install into. If your login has access to more than one, make sure you install into the one this
  connection is for.

## 1. Authorize with HubSpot

1. Open the HubSpot connection in Apideck Vault and click **Authorize**. Vault redirects you to
   HubSpot.
2. Sign in with the HubSpot account this connection should use. If HubSpot asks which account to
   install the app into, choose the one this connection is for.
3. Review the access HubSpot lists on the install screen and confirm it.
4. HubSpot returns you to Vault and the connection is authorized.

You are never asked for a redirect URL, a client ID, or a client secret. Those belong to the
HubSpot app held by the provider of the integration: see the
[HubSpot OAuth credentials guide](https://developers.apideck.com/connectors/hubspot/docs/application_owner+oauth_credentials)
if you are the one who set that app up.

## 2. Set the defaults for new records

HubSpot has a few settings in Vault that decide what happens to records the integration creates
without specifying every field. Set them **after** authorizing: the dropdowns are populated live
from your own HubSpot account, so they need the connection to be in place first.

| Resource | Setting | Required | What it does |
|---|---|---|---|
| Opportunities | **Pipeline** | Yes | The pipeline an opportunity is created in when the request does not name one. Lists the pipelines in your HubSpot account. |
| Opportunities | **Stage** | Yes | The stage within that pipeline. The list is filtered to the pipeline you picked above, so choose the pipeline first. |
| Contacts | **Lifecycle stage** | No | The lifecycle stage applied to every contact the integration creates while this setting has a value. Leave it empty to let HubSpot's own default apply. |
| Leads | **Lifecycle stage** | No | The same, for newly created leads. It is a separate setting from the contacts one even though the label is identical: set both if you create both. |

**Pipeline** and **Stage** are the two required ones, and they are worth a deliberate choice rather
than the first entry in the list: every opportunity the integration creates without an explicit
pipeline and stage lands where you point them here. An integration can still name a different
pipeline and stage on an individual request, so an opportunity that appears somewhere other than
these defaults is expected behaviour rather than a broken setting. The **Lifecycle stage** settings
work differently: a request cannot override them, so they are the only place that value comes from.

You may also see a free-text **Portal id** field. It belongs to HubSpot's tracking-script surface,
not to the CRM or Lead APIs: no CRM or Lead operation in this connector reads it. Leave it blank
unless the provider of the integration asks you to fill it in.

## Notes

- **Token refresh is automatic.** HubSpot access tokens are short-lived (30 minutes) and Apideck
  refreshes them for you. There is nothing to rotate, re-enter, or monitor, and HubSpot documents
  no scheduled expiry for the underlying authorization.
- **Uninstalling the app in HubSpot ends the connection.** This is the one action that reliably
  breaks it. If the app is uninstalled from **Integrations → Connected Apps** in your HubSpot
  settings (**Actions → Uninstall**), the connection stops working until someone authorizes it again
  in Vault, and because HubSpot treats that re-install as a brand-new app with no granted
  permissions, whoever does it needs the **App Marketplace Access** permission again. See
  [Connect apps to HubSpot](https://knowledge.hubspot.com/integrations/connect-apps-to-hubspot).
- **A connected app is not left without an owner when someone leaves.** If the HubSpot user who owns
  the app is deactivated, HubSpot prompts for ownership to be reassigned before completing the
  deactivation. See
  [Manage your connected apps](https://knowledge.hubspot.com/integrations/manage-your-connected-apps).
- **Re-authorizing is safe and is the standard repair.** Opening the connection in Vault and
  clicking **Authorize** again is the fix for most problems below; it does not require you to
  gather anything first. The one thing to line up first is the permission above, if the app was
  uninstalled in the meantime.

## Troubleshooting

**"Couldn't complete the connection. You don't have permission to connect this integration."**
Your HubSpot user is missing the **App Marketplace Access** permission, or one of the permissions
the app's scopes require. Ask a HubSpot account admin to grant App Marketplace Access, then check
the app listing's **Requirements → HubSpot Account permissions** for anything else you are missing:
**Edit property settings** is the usual one. HubSpot's
[Resolve a 'Request for Integration Permissions' error](https://knowledge.hubspot.com/integrations/resolve-a-request-for-integration-permissions-error)
walks an admin through it. Then click **Authorize** again.

**Authorization fails with an "insufficient scopes" error.**
The scopes configured on the HubSpot app do not match the scopes Apideck requests, so HubSpot
refuses the install. Nothing on your side can change this and re-trying will not clear it: report
it to the provider of the integration. They own the HubSpot app and can correct its scopes, after
which your **Authorize** click will go through.

**The wrong HubSpot account got connected.**
The connection is anchored to the account the app was installed into. Sign in to HubSpot as the
account you actually want (or switch accounts there), then run **Authorize** again on the
connection.

**New opportunities show up in an unexpected pipeline or stage.**
Check the **Pipeline** and **Stage** settings on the connection (step 2): those are the defaults
used whenever a request does not name its own. If the integration sets them per request, the
setting is not what decides it; raise it with the provider of the integration.

**New contacts or leads have an unexpected lifecycle stage.**
Only two things can produce it: the **Lifecycle stage** setting for that resource, and, when that
setting is empty, HubSpot's own default. A request cannot override the setting, so start there:
clear it to fall back to HubSpot's default, or set it to the stage you want.

**Requests start failing with `429`.**
That is HubSpot's rate-limit answer, not a broken connection: nothing needs re-authorizing and it
recovers on its own once the window resets. The budget is shared by every connection using the same
HubSpot app for your account, so it can be tripped by activity that is not yours. If it keeps
happening, report it to the provider of the integration: pacing the calls is theirs to manage, and
the current limits are listed in this connector's
[overview](https://developers.apideck.com/connectors/hubspot).

**The connection worked and later stopped.**
The usual causes, in order:

1. The app was uninstalled in HubSpot: authorize again in Vault, using a HubSpot user that has
   **App Marketplace Access**, since HubSpot treats the re-install as a brand-new app with no
   granted permissions.
2. The HubSpot app credentials behind the integration changed. That sits with the provider of the
   integration and affects every connection using them, so report it to them rather than
   re-authorizing repeatedly.

Still stuck? Contact [Apideck Support](https://help.apideck.com/en/articles/7774658).


[API reference](https://developers.apideck.com/apis/crm/reference.md) · [Coverage matrix](https://developers.apideck.com/apis/crm/coverage)