> ## 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.
</Note>

## 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:

<Steps>
  <Step title="Open HubSpot Settings">
    Go to your HubSpot account **Settings** and navigate to **Integrations** → **Private Apps**.
  </Step>

  <Step title="Create the App">
    Click **Create a private app** and give it a name (e.g., "Formbricks Integration").
  </Step>

  <Step title="Configure Scopes">
    Under **Scopes**, add `crm.objects.contacts.write` and `crm.objects.contacts.read`.
  </Step>

  <Step title="Get Your Access Token">
    Click **Create app** and copy the access token.
  </Step>
</Steps>

<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).
</Note>

***

## 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 publishing. If your survey is already published, duplicate it and update the question IDs in the copy.
</Note>

<Steps>
  <Step title="Set Up Your Survey">
    Make sure your survey has meaningful `questionId` values for each question. This makes mapping responses to HubSpot fields easier.

    <img src="https://mintcdn.com/formbricks/hX4eoMhsUTcFz4G1/images/xm-and-surveys/core-features/integrations/make/update-question-id.webp?fit=max&auto=format&n=hX4eoMhsUTcFz4G1&q=85&s=03ecf3bedc97dc2804f314faa9702fe1" alt="Update Question ID" width="931" height="363" data-path="images/xm-and-surveys/core-features/integrations/make/update-question-id.webp" />
  </Step>

  <Step title="Create a New Make.com Scenario">
    Go to [Make.com](https://make.com) and create a new scenario. Search for **Formbricks** and select it as your trigger, then choose **Response Finished** as the trigger event.

    <img src="https://mintcdn.com/formbricks/hX4eoMhsUTcFz4G1/images/xm-and-surveys/core-features/integrations/make/search-formbricks.webp?fit=max&auto=format&n=hX4eoMhsUTcFz4G1&q=85&s=00c4b2f985d64929b14b96785bd8d2a2" alt="Search Formbricks" width="1696" height="636" data-path="images/xm-and-surveys/core-features/integrations/make/search-formbricks.webp" />
  </Step>

  <Step title="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](/api-reference/rest-api#how-to-generate-an-api-key)), and select the survey you want to connect.

    <img src="https://mintcdn.com/formbricks/hX4eoMhsUTcFz4G1/images/xm-and-surveys/core-features/integrations/make/enter-api-key-and-host.webp?fit=max&auto=format&n=hX4eoMhsUTcFz4G1&q=85&s=146cb349538c6bc1419876f0b672e99d" alt="Enter API Key" width="1248" height="954" data-path="images/xm-and-surveys/core-features/integrations/make/enter-api-key-and-host.webp" />
  </Step>

  <Step title="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.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="Test and Activate">
    Submit a test response to your Formbricks survey, verify the contact appears in HubSpot, and turn on your Make scenario.
  </Step>
</Steps>

***

## 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`.
</Note>

<Steps>
  <Step title="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.

    <img src="https://mintcdn.com/formbricks/hX4eoMhsUTcFz4G1/images/xm-and-surveys/core-features/integrations/n8n/add-formbricks-trigger.webp?fit=max&auto=format&n=hX4eoMhsUTcFz4G1&q=85&s=4b53fcf705f002cef1bb9279e959b24d" alt="Add Formbricks Trigger" width="1050" height="1044" data-path="images/xm-and-surveys/core-features/integrations/n8n/add-formbricks-trigger.webp" />
  </Step>

  <Step title="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).
  </Step>

  <Step title="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`.
  </Step>

  <Step title="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.
  </Step>
</Steps>

***

## 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.
</Note>

<Steps>
  <Step title="Create a Formbricks Webhook">
    Go to **Configuration** → **Integrations** in Formbricks, click **Manage Webhooks** → **Add Webhook**, enter your endpoint URL, select **Response Finished** as the trigger, and choose the surveys to monitor.

    <img src="https://mintcdn.com/formbricks/Q9LOxgpWHulOxfHK/images/xm-and-surveys/core-features/integrations/webhooks/integrations-tab.webp?fit=max&auto=format&n=Q9LOxgpWHulOxfHK&q=85&s=d202857933cba10c8ad2b139e82d9d41" alt="Integrations Tab" width="3534" height="1988" data-path="images/xm-and-surveys/core-features/integrations/webhooks/integrations-tab.webp" />
  </Step>

  <Step title="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](/xm-and-surveys/core-features/integrations/webhooks).
  </Step>

  <Step title="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.
  </Step>
</Steps>

***

## 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!