HubSpot Marketing Hub

Log into your HubSpot account. Click the **Settings** gear icon (top-right navigation bar), then in the left sidebar navigate to **Integrations → Private Apps**. Click **Create a private app**. Give the app a descriptive name such as 'Bubble Integration'. On the Scopes tab, you must explicitly select each permission category your Bubble integration will need. HubSpot scopes are additive — selecting the wrong or incomplete set of scopes causes 403 errors later, and you cannot add scopes to an existing Private App without deleting and recreating it. For the workflows in this tutorial, select at minimum: - `crm.objects.contacts.write` — to create and update contacts - `crm.objects.contacts.read` — to read contact data - `forms` — to submit form data programmatically - `marketing-email` — to read email campaign statistics (Marketing Hub Starter or above required) Click **Create app**. HubSpot displays your access token once — this is the only time it is shown in full. Copy it immediately and save it somewhere secure (a password manager, a Bubble App Data field, or your notes — but not in code or a visible text element). Important: this token grants whatever scopes you selected across your entire HubSpot portal. Treat it like a password.

Open your Bubble app editor. Click the **Plugins** tab in the left sidebar, then **Add plugins**. Search for **API Connector** (the official Bubble plugin) and click **Install**. After installation, click **API Connector** in the Plugins tab to expand the configuration panel. Click **Add another API** and name the group **HubSpot Marketing**. Under **Shared headers for all calls**, add two headers: 1. Header name: `Authorization` — Value: `Bearer YOUR_PRIVATE_APP_TOKEN` (replace with your actual token) — enable the **Private** checkbox. This is the critical security step: the Private flag tells Bubble to execute this header server-side only, never exposing the token to browser network traffic. 2. Header name: `Content-Type` — Value: `application/json` — leave Private unchecked (this is not sensitive). Set the shared base URL to `https://api.hubapi.com` — all HubSpot API v3 endpoints share this base URL, with the path specified at the individual call level. Bubble proxies every API Connector call from its own servers. A HubSpot Private App token grants full portal access across its configured scopes — keeping it Private in the header is essential.

1{
2  "group_name": "HubSpot Marketing",
3  "base_url": "https://api.hubapi.com",
4  "shared_headers": [
5    {
6      "name": "Authorization",
7      "value": "Bearer <your_private_app_token>",
8      "private": true
9    },
10    {
11      "name": "Content-Type",
12      "value": "application/json",
13      "private": false
14    }
15  ]
16}

Inside the HubSpot Marketing group, click **Add another call**. Name it **Get Contacts** (this will be your verification call). Set the method to **GET** and enter the path: `/crm/v3/objects/contacts`. No body is needed for a GET request. Set **Use as** to **Data**. Click **Initialize call** — Bubble sends the request with your Private Authorization header and displays the response in the preview panel. A successful response shows a JSON object with a `results` array, each element being a HubSpot contact object with `id`, `properties`, and `createdAt` fields. Bubble auto-detects these fields and makes them accessible in dynamic expressions. If the call returns a **401 Unauthorized**: the token value in the Authorization header is incorrect or was not copied completely. Open the header, re-paste the token, and retry. If the call returns a **403 Forbidden**: the token is valid but your Private App is missing the `crm.objects.contacts.read` scope. Go back to HubSpot → Settings → Private Apps → your app → Scopes, add the missing scope, and regenerate. Note: updating scopes on an existing Private App does generate a new token — copy it and update the Bubble API Connector header. This Initialize Call is also how Bubble learns the shape of HubSpot's contact response — field names detected here are reusable in all contact-related workflows.

Add a new call inside the HubSpot Marketing group. Name it **Create Contact**. Set method to **POST** and path to `/crm/v3/objects/contacts`. Under Body, select **JSON** as the body type. The HubSpot contacts API expects a `properties` object wrapping all contact field values. Add dynamic parameters for email, firstname, and lastname: ```json { "properties": { "email": "<email>", "firstname": "<firstname>", "lastname": "<lastname>" } } ``` Toggle `email`, `firstname`, and `lastname` values to dynamic in Bubble's body editor. Set **Use as** to **Action** (since this creates data, not retrieves it). Click **Initialize call** using a real test email address for the `email` parameter — HubSpot requires a valid email format and will return a 400 if the test email is invalid or already exists as a contact. Now wire this to the sign-up workflow: in Bubble's Workflow editor, find the workflow that creates a new User (or your sign-up button's workflow). Add a step at the end: **Plugins → HubSpot Marketing - Create Contact**. Bind `email` to the sign-up email input's value (or `Current User's email` if the User is already created), `firstname` to the first name input, and `lastname` to the last name input. This means every Bubble registration triggers a HubSpot contact creation, which in turn fires any HubSpot Marketing Hub workflows assigned to new contacts (welcome sequences, sales assignment, etc.).

1{
2  "properties": {
3    "email": "<email>",
4    "firstname": "<firstname>",
5    "lastname": "<lastname>"
6  }
7}

HubSpot forms are a powerful trigger mechanism — submitting to a form endpoint creates or updates a contact AND fires any Marketing Hub workflows (email sequences, lifecycle stage changes, deal creation) associated with that form. Add a new call inside the HubSpot Marketing group. Name it **Submit Form**. Set method to **POST** and path to: `/submissions/v3/integration/submit/<portalId>/<formGuid>` You need two static values: - **portalId**: your HubSpot portal's numeric ID, visible in the URL when logged into HubSpot: `app.hubspot.com/contacts/{portalId}/` - **formGuid**: the unique ID of the HubSpot form you want to submit to, found in the form's embed code at HubSpot → Marketing → Lead Capture → Forms → {your form} → Embed → the `formId` value in the embed snippet In Bubble's API Connector, replace `<portalId>` and `<formGuid>` in the path with your actual numeric values (they don't change, so hardcoding is fine). The body format uses a `fields` array: ```json { "fields": [ { "name": "email", "value": "<email>" }, { "name": "firstname", "value": "<firstname>" }, { "name": "message", "value": "<message>" } ], "context": { "pageUri": "https://yourapp.bubbleapps.io/contact", "pageName": "Contact Page" } } ``` Toggle `email`, `firstname`, and `message` to dynamic. Wire this call to a Bubble form's submit button workflow. This approach lets you use Bubble's native form elements while still triggering HubSpot automation sequences — no HubSpot embed code required on the page.

1{
2  "fields": [
3    { "name": "email", "value": "<email>" },
4    { "name": "firstname", "value": "<firstname>" },
5    { "name": "message", "value": "<message>" }
6  ],
7  "context": {
8    "pageUri": "https://yourapp.bubbleapps.io/contact",
9    "pageName": "Contact Page"
10  }
11}

For founders who want a custom reporting view of their HubSpot email campaigns inside Bubble, the Marketing Hub API provides endpoint for campaign-level metrics. Add a new call inside the HubSpot Marketing group. Name it **Get Email Campaigns**. Set method to **GET** and path to `/marketing/v3/emails`. Set **Use as** to **Data**. Click **Initialize call** — this returns a list of your email campaigns with metadata including `name`, `subject`, `sendDate`, and content ID. For per-campaign statistics, add a second call named **Get Campaign Stats**. Set method to **GET** and path to `/marketing/v3/emails/<contentId>/statistics/by-filters` where `<contentId>` is a dynamic parameter bound to the selected campaign's ID. Initialize this call with a real campaign content ID from the previous call's results. Build the UI: 1. Add a Repeating Group with Type = Get Email Campaigns and Data source = the Get Email Campaigns API call result's `results` list. 2. Inside the Repeating Group, show `Current cell's name`, `Current cell's subject`, and a clickable element to load stats. 3. When a campaign row is clicked, trigger a workflow calling Get Campaign Stats with the row's content ID, then display the open rate, click rate, and delivery metrics in a popup or separate panel. Note: Email campaign endpoints require the `marketing-email` scope on your Private App and Marketing Hub Starter or above on your HubSpot subscription. Free CRM accounts cannot access this endpoint.