# HubSpot Integration

Connect Guideflow to HubSpot to automatically create and update contacts based on how prospects engage with your flows. As viewers interact with your flows, their engagement data is pushed directly into HubSpot so your sales and marketing teams always have the most current picture of prospect activity.

{% hint style="info" %}
You must have **Admin** level permissions to connect any integrations within Guideflow.
{% endhint %}

{% @guideflow/guideflow-embed requestedUrl="<https://app.guideflow.com/embed/xrglq2twk0>" %}

### **How to connect**

* Navigate to **Integrations** in your Guideflow dashboard.
* Find **HubSpot** under CRM and click **Install**.
* A HubSpot authorization window will open. Sign in and grant the requested permissions.
* Once authorized, the integration is active. Guideflow will automatically create a custom property group and contact properties in HubSpot.
* Toggle on the **events** you want to track. All events are disabled by default.
* Choose whether to enable the integration for **all flows** or select specific ones.

{% hint style="info" %}
HubSpot integration uses OAuth authorization. No API keys or manual configuration are needed on the HubSpot side.
{% endhint %}

***

### **How it works**

Guideflow pushes data to HubSpot only when a viewer's contact information is collected. This happens in one of two ways:

* A viewer submits a **lead capture form** inside the flow.
* A viewer arrives via a **custom link** that includes their contact information as a variable.

Once contact information is captured, Guideflow searches HubSpot for an existing contact matching the email, phone, or name provided. If a match is found, the existing contact is updated. If no match is found, a new contact is created. All subsequent engagement data from that session is then pushed to that contact record in real time as the viewer progresses through the Guideflow.

***

### Events Tracked

Guideflow supports 5 event types for HubSpot. Each event can be individually enabled or disabled from the integration settings.

<table><thead><tr><th width="189.29296875">Event</th><th>What it does</th></tr></thead><tbody><tr><td>First Interaction</td><td>Triggered when a viewer starts a flow session. Creates or updates the contact in HubSpot if lead data is available.</td></tr><tr><td>Lead Created</td><td>Creates or updates a HubSpot contact with the viewer's information submitted via a form or custom link.</td></tr><tr><td>Step Viewed</td><td>Updates the contact with the current step details and completion percentage each time a viewer moves through a step.</td></tr><tr><td>Completed</td><td>Updates the contact with a completion status and 100% completion percentage when the viewer reaches the final step.</td></tr><tr><td>External Link Clicked</td><td>Updates the contact with a CTA clicked flag when the viewer clicks an external link in the flow.</td></tr></tbody></table>

### **Contact fields mapped to HubSpot**

When a viewer submits a lead form, Guideflow maps the following fields directly to the HubSpot contact record:

<table><thead><tr><th width="235.1474609375">Guideflow form field</th><th>HubSpot contact field</th></tr></thead><tbody><tr><td>First Name</td><td><code>firstname</code></td></tr><tr><td>Last Name</td><td><code>lastname</code></td></tr><tr><td>Email</td><td><code>email</code></td></tr><tr><td>Company</td><td><code>company</code></td></tr><tr><td>Phone</td><td><code>phone</code></td></tr><tr><td>Website</td><td><code>website</code></td></tr></tbody></table>

### **Guideflow properties created in HubSpot**

When the integration is first connected, Guideflow automatically creates a **Guideflow** property group on HubSpot contacts with the following custom properties. These are populated as the viewer interacts with the flow and can be used to build contact views, lists, segments, workflows, and reports in HubSpot.

<table><thead><tr><th width="300.0986328125">Property</th><th>Description</th></tr></thead><tbody><tr><td><code>guideflow_session_id</code></td><td>Unique identifier for the viewer's session</td></tr><tr><td><code>guideflow_url</code></td><td>URL where the guideflow was embedded or shared</td></tr><tr><td><code>guideflow_workspace_id</code></td><td>Identifier of the Guideflow workspace</td></tr><tr><td><code>guideflow_folder_id</code></td><td>Identifier of the folder containing the guideflow</td></tr><tr><td><code>guideflow_folder_name</code></td><td>Name of the folder containing the guideflow</td></tr><tr><td><code>guideflow_id</code></td><td>Unique identifier of the guideflow</td></tr><tr><td><code>guideflow_name</code></td><td>Name of the guideflow</td></tr><tr><td><code>guideflow_step_id</code></td><td>Identifier of the last step viewed</td></tr><tr><td><code>guideflow_step_index</code></td><td>Position of the last step viewed</td></tr><tr><td><code>guideflow_step_name</code></td><td>Name of the last step viewed</td></tr><tr><td><code>guideflow_steps_total_number</code></td><td>Total number of steps in the guideflow</td></tr><tr><td><code>guideflow_percent_of_completion</code></td><td>How far the viewer progressed (0 to 100%)</td></tr><tr><td><code>guideflow_time_spend</code></td><td>Time spent on the last step viewed</td></tr><tr><td><code>guideflow_is_completed</code></td><td>Whether the viewer completed the guideflow</td></tr><tr><td><code>guideflow_cta_clicked</code></td><td>Whether the viewer clicked an external link</td></tr><tr><td><code>guideflow_cta_clicked_location</code></td><td>Where in the guideflow the external link was clicked</td></tr></tbody></table>

### How to manage Guideflow properties in Hubspot

{% @guideflow/guideflow-embed requestedUrl="<https://app.guideflow.com/embed/qp7mqvcjp3>" %}

### **How to use Guideflow data in HubSpot**

Once the integration is live and contacts are being created, you can use Guideflow properties in HubSpot to:

* **Contact views:** see Guideflow engagement data directly on any contact record.
* **Lists and segments:** filter contacts by completion status, CTA clicks, specific guideflows, or folders.
* **Workflows:** trigger follow-up actions based on demo engagement, such as sending an email when a viewer completes a guideflow.
* **Reports:** build custom reports on how prospects are engaging with your demos across the buyer journey.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.guideflow.com/help/integrations/crm-integrations/hubspot-integration-1.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.