> ## Documentation Index > Fetch the complete documentation index at: https://docs.withampersand.com/llms.txt > Use this file to discover all available pages before exploring further. # HubSpot ## What's Supported ### Supported Actions The Hubspot connector supports: * [Read Actions](/read-actions), including full historic backfill, incremental reads, and filters. * [Subscribe Actions](/subscribe-actions). Please note that [special set up](#set-up-subscribe-actions) is needed for HubSpot. * [Write Actions](/write-actions), including Bulk Write and Delete. * [Proxy Actions](/proxy-actions), using the base URL `https://api.hubapi.com`. ### Supported Objects #### CRM Objects The connector supports reading from and writing to the following *CRM objects*, including [standard fields](https://docs.google.com/spreadsheets/d/1FGc9zT_J9dyGghDxvqeioAva-5Gj7-2DQzKNMrbrPvw/view?usp=sharing) and custom fields: * [calls](https://developers.hubspot.com/docs/api-reference/legacy/crm/activities/calls/guide) * [companies](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/companies/guide) * [contacts](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/guide) * [deals](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/deals/guide) * [emails](https://developers.hubspot.com/docs/api-reference/legacy/crm/activities/emails/guide) * [meetings](https://developers.hubspot.com/docs/api-reference/legacy/crm/activities/meetings/guide) * [notes](https://developers.hubspot.com/docs/api-reference/legacy/crm/activities/notes/guide) * All other [standard CRM objects](https://developers.hubspot.com/docs/guides/crm/understanding-the-crm#object-type-ids) * Custom CRM objects The connector only supports reading from: * [lists](https://developers.hubspot.com/docs/api-reference/latest/crm/lists/guide) (note: incremental reads not supported for Lists) * Users and owners ([see below](#reading-users-and-owners)) #### Marketing Objects The connector supports reading from: * [marketing-campaigns](https://developers.hubspot.com/docs/api-reference/latest/marketing/campaigns/guide) * [marketing-forms](https://developers.hubspot.com/docs/api-reference/2026-09-beta/marketing/forms/guide) * [marketing-events](https://developers.hubspot.com/docs/api-reference/latest/marketing/marketing-events/guide) * [marketing-emails](https://developers.hubspot.com/docs/api-reference/latest/marketing/marketing-emails/guide) #### Conversation Objects The connector supports reading from: * [channel-accounts](https://developers.hubspot.com/docs/api-reference/2026-09-beta/conversations/conversations/channel-accounts/get-channel-accounts) * [channels](https://developers.hubspot.com/docs/api-reference/2026-09-beta/conversations/conversations/channels/get-channels) * [custom-channels](https://developers.hubspot.com/docs/api-reference/latest/conversations/custom-channels/channels/get-custom-channels) * [inboxes](https://developers.hubspot.com/docs/api-reference/2026-09-beta/conversations/conversations/inbox/get-inboxes) * [threads](https://developers.hubspot.com/docs/api-reference/2026-09-beta/conversations/conversations/threads/get-threads) #### Communication Objects The connector supports reading from: * [communication-preferences](https://developers.hubspot.com/docs/api-reference/latest/communication-preferences/guide) #### Scheduler Objects The connector supports reading from: * [meeting-links](https://developers.hubspot.com/docs/api-reference/latest/scheduler/meetings/get-meeting-links) #### Event Occurrences Event occurrences represent specific actions captured at a point in time, such as form submissions, email delivery, sequence activity, and other **behavioral changes**. They are useful to understand when an event happened and how that event may relate to automation or downstream workflows. To find the event type you are interested in, use the HubSpot Events API's [list event types endpoint](https://developers.hubspot.com/docs/api-reference/latest/events/retrieve-events/get-event-types) and [list custom event definitions](https://developers.hubspot.com/docs/api-reference/latest/events/define-events/create-event-definition). Standard event type names begin with `e_`, while customer-specific custom event definitions use the `fullyQualifiedName` property with a `pe{HubId}_` prefix. Standard events are safe to use across all customers, while custom event definitions apply only to the specific customer account where they are defined. The HubSpot connector exposes event types as individual objects that follow the convention `AMPERSAND-event-occurrences-`. Note that **occurrences** is spelled with two c's and two r's. Here are a few examples of the objects you would read for different event types - * `AMPERSAND-event-occurrences-e_call_ended` * `AMPERSAND-event-occurrences-e_form_submission` * `AMPERSAND-event-occurrences-e_mta_bounced_email_v2` * `AMPERSAND-event-occurrences-e_visited_page` * `AMPERSAND-event-occurrences-pe148543157_this_is_my_event` #### Reading users and owners To read users from your customer's HubSpot workspace, enable the `crm.objects.users.read` scope and add `users` as an object in `amp.yaml`: ```YAML theme={null} - objectName: users destination: defaultWebhook schedule: "0 0 * * *" requiredFields: - fieldName: hs_object_id mapToName: userId - fieldName: hubspot_owner_id mapToName: ownerId - fieldName: hs_email mapToName: emailAddress ``` ### Associations HubSpot associations is a private preview feature where you can retrieve associated records when using Read Actions or Subscribe Actions. Please contact [support@withampersand.com](mailto:support@withampersand.com) if you wish to use it. ### Example Integration For an example manifest file, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/hubspot/amp.yaml). ## Before You Get Started If you don't already have one, sign up for a [free HubSpot developer account](https://app.hubspot.com/signup-hubspot/crm?intent=developer). ## Create a HubSpot App ### Method 1: New Project Apps New Project Apps are [limited to 25 installs](https://developers.hubspot.com/changelog/new-marketplace-distribution-app-install-limits), until the app is listed on the HubSpot Marketplace. We recommend starting the process to [publish to HubSpot marketplace](#publish-to-hubspot-marketplace) as soon you've finished building your integration and tested it internally or with a customer. To create a New Project App: 1. **Open** the terminal 2. **Install** the HubSpot CLI: `npm install -g @hubspot/cli` 3. **Authenticate** using `hs account auth` and select open HubSpot to get your key Alt text If you already have a personal access key, select "Enter existing personal access key" and skip to [Step 7](#create-project). 4. **Select** your account (if prompted) If you have multiple accounts, make sure to select the developer account. 5. **Create** your Personal Access Key and copy it Alt text 6. **Go back** to terminal, **paste** the key and **hit Enter** Alt text 7. Create a project: Copy and paste this command in the terminal: ``` hs project create --name your-project-name --project-base app --distribution marketplace --auth oauth --features ``` 8. Configure OAuth redirect URL and scopes Open the folder where the HubSpot project was created and edit `src/app/app-hsmeta.json`. Replace the `auth` section of the file with the snippet below. If you wish to read or write to more objects than **contacts**, then add more scopes. For example, if you also want to read **companies**, then you can add the following scopes: * crm.objects.companies.read For a full list of HubSpot scopes, please refer to [HubSpot documentation](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/scopes#list-of-available-scopes). ```json theme={null} { "auth": { "type": "oauth", "redirectUrls": ["https://api.withampersand.com/callbacks/v1/oauth"], "requiredScopes": [ "oauth", "crm.objects.contacts.read", "crm.objects.contacts.write" ], "optionalScopes": [], "conditionallyRequiredScopes": [] } } ``` 9. **Deploy**: run the following command ``` hs project upload ``` You will be prompted to create the new project, select "yes". Alt text 10. Accept HubSpot's Acceptable Use Policy If this is your first time create a HubSpot app, you will need to accept HubSpot's Acceptable Use Policy before any users can install your integration. * Log into HubSpot * Select **Development** from the bottom of the left nav bar. Dev tab * Select the project you just created Select Project * In the **Project Components** section, click on the app. Select App * Navigate to the **Distribution** tab, click on "Begin Publishing" and complete the first step "Agree to HubSpot's Acceptable Use Policy". You do not need to complete the rest of the steps right now. Acceptable Use Policy 11. Get Client ID and Client Secret * Follow the steps from Step 10 above to navigate to your HubSpot app. * Go to the **Auth** tab to find your **Client ID** and **Client Secret** Auth 12. Jump to [Add App to Ampersand](#add-app-to-ampersand). ### Method 2: Legacy Apps Legacy Apps has no install limits but [won't receive new HubSpot features](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/overview). When you migrate a Legacy App to a new Project App, you will be subject to the 25 install limit until your app is listed in the HubSpot marketplace. Please see [HubSpot changelog](https://developers.hubspot.com/changelog/new-marketplace-distribution-app-install-limits) for more details. Depending on when you created your HubSpot developer account, you will see different UI. #### Developer accounts created after September 2025 1. Log in to your HubSpot developer account 2. Navigate to **Development** → **Legacy apps** Alt text If you don't see the Development menu, you need Super Admin permissions. 3. Click **Create** → Select **Public** Alt text 4. Enter **Public app name** and go to the **Auth** tab Add Redirect URL: `https://api.withampersand.com/callbacks/v1/oauth` and click "Create app" Alt text 5. Go to the Scopes section, click "Add new scope" and **select your required scopes** Alt text 6. **Copy your Client ID and Client Secret** from the Auth tab Alt text Jump to [Add App to Ampersand](#add-app-to-ampersand). #### Developer accounts created before September 2025 1. Log in to your [HubSpot Developer Dashboard](https://app.hubspot.com/signup-hubspot/developers) 2. Click **Create an app** Alt text 3. Enter **Public app name**, click the **Auth** tab, add Redirect URL: `https://api.withampersand.com/callbacks/v1/oauth` and click "Create app" Alt text 4. Go to the **Scopes** tab and select your required scopes Alt text 5. Copy your **Client ID** and **Client Secret** from the Auth tab Alt text Jump to [Add App to Ampersand](#add-app-to-ampersand) ## Add App to Ampersand After creating your app using any method above: 1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com) 2. Select your project → **Provider apps** 3. Select **HubSpot** from the Provider list 4. Enter your **Client ID**, **Client Secret**, and **Scopes** and click **Save changes**. These scopes must should match the exact set of scopes defined in your HubSpot app. Alt text ## Using the connector To start integrating with HubSpot: * Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/hubspot/amp.yaml) * Deploy it using the [amp CLI](/cli/overview) * If using Read or Subscribe Actions, create a [destination](/destinations) * Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component * Start using the connector! ## Set up Subscribe Actions HubSpot subscribe actions cannot notify you of changes to custom fields. There is a workaround that requires additional set up, please contact [support@withampersand.com](mailto:support@withampersand.com) for details. To enable HubSpot subscribe actions, you will need to: * Define the subscribe action in your `amp.yaml` file and then deploy it. See the [Subscribe Actions documentation](/subscribe-actions) for details. * Make modifications to the HubSpot app (see below). ### New project apps If you are using a new project app (that was created with the HubSpot CLI), then follow the instructions below. If you don't have any apps yet, follow the instructions in [Method 1: New Project Apps](#method-1-new-project-apps) above to create one. #### Create webhooks-hsmeta.json file Go to the directory that contains your HubSpot app, and add a file called `your-project-name/src/app/webhooks/webhooks-hsmeta.json`. So your directory should end up like this: ``` /your-project-name /src/app /webhooks webhooks-hsmeta.json app-hsmeta.json hsproject.json ``` Replace `targetUrl` in the example `webhooks-hsmeta.json` file below with the one that is for your integration. It should follow the format: ``` "https://subscribe-webhook.withampersand.com/v1/projects/PROJECT_ID/integrations/INTEGRATION_ID" ``` * Replace `PROJECT_ID` with your Ampersand project ID, which can be found in the Dashboard's [General Settings page](https://dashboard.withampersand.com/projects/_/settings). * Replace `INTEGRATION_ID` with your integration's ID, which can be found in the Dashboard's [Home page](https://dashboard.withampersand.com/projects/_). You can also edit the file with the desired objects and events you want to subscribe to. You can refer to [HubSpot documentation](https://developers.hubspot.com/docs/apps/developer-platform/add-features/configure-webhooks#webhook-configuration) for the syntax of this file. Example `webhooks-hsmeta.json`: ``` { "uid": "ampersand_subscribe_actions", "type": "webhooks", "config": { "settings": { "targetUrl": "SEE_INSTRUCTIONS_ABOVE", "maxConcurrentRequests": 50 }, "subscriptions": { "crmObjects": [ { "subscriptionType": "object.creation", "objectType": "contact", "active": true }, { "subscriptionType": "object.propertyChange", "objectType": "contact", "propertyName": "firstname", "active": true }, { "subscriptionType": "object.propertyChange", "objectType": "contact", "propertyName": "lastname", "active": true }, { "subscriptionType": "object.deletion", "objectType": "contact", "active": true } ] } } } ``` #### Deploy changes to HubSpot Once you are done editing `webhooks-hsmeta.json`, deploy it using the following command: ``` hs project upload ``` ### Legacy apps If you have a legacy app (that was created in the HubSpot UI), follow the instructions below. 1. Login to your HubSpot account. 2. Go to the **Apps** section. 3. Select your connected app. 4. Click on **Webhooks**. 5. Enter the Target URL: ``` https://subscribe-webhook.withampersand.com/v1/projects/PROJECT_ID/integrations/INTEGRATION_ID ``` * Replace `PROJECT_ID` with your Ampersand project ID, which can be found in the Dashboard's [General Settings page](https://dashboard.withampersand.com/projects/_/settings). * Replace `INTEGRATION_ID` with your integration's ID, which can be found in the Dashboard's [Home page](https://dashboard.withampersand.com/projects/_). 7. Click **Create Subscription**. 8. Select object types, event types, and properties. 9. Select the required checkboxes for all objects. 10. Click **Activate**. Subscribe actions HubSpot ## Customer guide Share the [HubSpot customer guide](/customer-guides/hubspot) with your customers to help them use your integration. ## Publish to HubSpot Marketplace When you are ready to list on the HubSpot marketplace, follow the instructions in the [HubSpot documentation](https://developers.hubspot.com/docs/apps/developer-platform/list-apps/listing-your-app/listing-your-app). * For the **App Information** section, you should use information about your company, not about Ampersand. * For **Install Button URL**, use the URL of your application that users go to to start the installation process (this is usually where you've embedded the Ampersand UI Component).