> ## Documentation Index
> Fetch the complete documentation index at: https://formbricks.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# HubSpot

> Learn how to integrate Formbricks with HubSpot to automatically create or update contacts when survey responses are submitted.

> [!NOTE]
>
> Formbricks doesn't have a native HubSpot integration yet. This guide shows you how to connect Formbricks with HubSpot using automation platforms (Make.com, n8n) or custom webhooks.

## Prerequisites

Before setting up the integration, you'll need:

1. **A Formbricks account** with at least one survey that collects email addresses
2. **A HubSpot account** with API access
3. **HubSpot API credentials** (see authentication options below)
4. **Automation service** like Make, n8n, or ActivePieces (for no-code methods)

### HubSpot Authentication Options

HubSpot offers two main ways to authenticate API requests:

#### Option A: OAuth 2.0 via Public App (Recommended)

OAuth is the recommended approach for production integrations. When using Make.com or n8n, they handle OAuth authentication for you through their built-in HubSpot connectors.

#### Option B: Legacy Private Apps (Simple Setup)

For custom webhook handlers, you can use a Legacy Private App which provides a static access token. While marked as "legacy," these apps remain fully supported by HubSpot.

To create a Legacy Private App:

**1. Open HubSpot Settings**

Go to your HubSpot account **Settings** and navigate to **Integrations** → **Private Apps**.

**2. Create the App**

Click **Create a private app** and give it a name (e.g., "Formbricks Integration").

**3. Configure Scopes**

Under **Scopes**, add `crm.objects.contacts.write` and `crm.objects.contacts.read`.

**4. Get Your Access Token**

Click **Create app** and copy the access token.

> [!NOTE]
>
> For more information on HubSpot's authentication options, see the [HubSpot Authentication Overview](https://developers.hubspot.com/docs/guides/apps/authentication/intro-to-auth).

***

## Method 1: Using Make.com (Recommended for No-Code)

> [!NOTE]
>
> Before starting, ensure your survey has clear `questionId` values set. You can only update these before activating the survey. If your survey is already activated, duplicate it and update the question IDs in the copy.

**1. Set Up Your Survey**

Make sure your survey has meaningful `questionId` values for each question. This makes mapping responses to HubSpot fields easier.

![Update Question ID](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/make/update-question-id.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=34ef2a99e6353651275474585b319bd6)

**2. Create a New Make.com Scenario**

Go to [Make.com](https://make.com) and create a new scenario. Search for **Formbricks** and select the **Watch Response Finished** trigger, not **Watch Response Created**, which fires as soon as the first question is answered and may run before the email field is filled in.

![Search Formbricks](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/make/search-formbricks.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=4ccc17e459b6999a6e5c9a2853548bda)

**3. Connect Formbricks to Make**

Click **Create a webhook**, enter your Formbricks API Host (default: `https://app.formbricks.com`), add your Formbricks API Key (see [API Key Setup](https://formbricks.com/docs/api-reference/generate-key.md)), and select the survey you want to connect.

![Enter API Key](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/make/enter-api-key-and-host.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=635a6374fc27d2f5935dbf1204937c7a)

**4. Add the HubSpot Module**

Click the **+** button after the Formbricks trigger, search for **HubSpot**, choose **Create or Update a Contact** as the action, and connect your HubSpot account.

**5. Map Formbricks Fields to HubSpot**

Map the Formbricks response fields to HubSpot contact properties:

| HubSpot Field | Formbricks Field |
| - | - |
| Email | `data.email` (your email question ID) |
| First Name | `data.firstName` (if collected) |
| Last Name | `data.lastName` (if collected) |
| Custom Property | Any other `data.*` field |

You can also map metadata: `meta.country`, `meta.userAgent.browser`, `survey.title`.

**6. Test and Activate**

Submit a test response to your Formbricks survey, verify the contact appears in HubSpot, and turn on your Make scenario.

***

## Method 2: Using n8n (Self-Hosted Option)

> [!NOTE]
>
> The Formbricks n8n node is available as a community node. Install it via **Settings** → **Community Nodes** → install `@formbricks/n8n-nodes-formbricks`.

**1. Set Up the Formbricks Trigger**

Create a new workflow in n8n, add the **Formbricks** trigger node, connect it with your Formbricks API Key and host, select **Response Finished** as the event, and choose your survey.

![Add Formbricks Trigger](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/n8n/add-formbricks-trigger.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=6ec754cf7fb282ae800595341304a2ea)

**2. Add the HubSpot Node**

Add a new node and search for **HubSpot**, select **Create/Update Contact** as the operation, and connect your HubSpot account (n8n supports both OAuth and access token authentication).

**3. Configure Field Mapping**

In the HubSpot node, map the fields:

```
Email: {{ $json.data.email }}
First Name: {{ $json.data.firstName }}
Last Name: {{ $json.data.lastName }}
```

For custom HubSpot properties, use the **Additional Fields** section to add mappings like `survey_source`, `response_id`, and `submission_date`.

**4. Test Your Workflow**

Click **Listen for event** in the Formbricks trigger, submit a test survey response, verify the data flows through to HubSpot, and activate your workflow.

***

## Method 3: Using Webhooks (Custom Integration)

For maximum flexibility, you can use Formbricks webhooks with a custom endpoint that calls the HubSpot API directly. This approach is ideal for developers who want full control.

> [!NOTE]
>
> This method requires a HubSpot access token. You can use a Legacy Private App token (simplest) or implement OAuth 2.0 for production applications.

**1. Create a Formbricks Webhook**

Go to **Settings → Workspace → Integrations** in Formbricks, click **Manage Webhooks** → **Add Webhook**, enter your endpoint URL, select **Response Finished** as the trigger, and choose the surveys to monitor.

![Integrations Tab](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/webhooks/integrations-tab.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=6701827c1d1c7b24eaec63f2c3450601)

**2. Build Your Webhook Handler**

Your webhook handler needs to:

* **Receive the Formbricks webhook** - Accept POST requests with the survey response payload
* **Extract contact data** - Parse the email and other fields from `data.data` (keyed by your `questionId` values)
* **Call the HubSpot API** - Use the [HubSpot Contacts API](https://developers.hubspot.com/docs/api/crm/contacts) to create or update contacts
* **Handle duplicates** - HubSpot returns a 409 error if a contact with that email exists; search and update instead

You can deploy using serverless functions (Vercel, AWS Lambda, Cloudflare Workers), traditional servers, or low-code platforms. For webhook signature verification, see the [Webhooks documentation](https://formbricks.com/docs/platform/features/integrations/webhooks.md).

**3. Deploy and Test**

Deploy your webhook handler to a publicly accessible URL, add the URL to your Formbricks webhook configuration, submit a test survey response, and verify the contact appears in HubSpot.

***

## Troubleshooting

### Contact Not Created in HubSpot

1. **Check the email field**: Ensure your survey has an email question and you're mapping the correct `questionId`
2. **Verify API token**: Make sure your HubSpot access token has the required scopes (`crm.objects.contacts.write` and `crm.objects.contacts.read`)
3. **Check for duplicates**: HubSpot returns a 409 error if a contact with that email already exists

### Webhook Not Triggering

1. Verify the webhook URL is publicly accessible
2. Check that **Response Finished** trigger is selected
3. Ensure the survey is linked to the webhook

### Testing Your Integration

1. Use a unique test email for each test
2. Check HubSpot's **Contacts** page after submitting a response
3. Review your webhook handler logs for errors

***

Still struggling or something not working as expected? [Join our GitHub Discussions](https://github.com/formbricks/formbricks/discussions) and we're happy to help!


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.