> For the complete documentation index, see [llms.txt](https://docs.perkville.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.perkville.com/integrations/integration-reference/hubspot.md).

# HubSpot

Bring Perkville referrals and loyalty information into HubSpot contacts and workflows.

## Integration at a glance <a href="#capabilities-and-use-cases" id="capabilities-and-use-cases"></a>

{% columns %}
{% column %}

### Referrals & rewards

* **Referral leads** — Create contacts from Perkville referrals through a configured lead sync.
  {% endcolumn %}

{% column %}

### Data & workflows

* **Program data** — Sync program status, point balance, last earned transaction and challenge participation.
* **Automation** — Use Perkville activity in HubSpot workflows and send program-relevant HubSpot data to Perkville.
* **Existing contacts** — Contact-update behavior depends on the workflow. The default referral-lead flow creates new contacts and does not update existing contacts.
  {% endcolumn %}
  {% endcolumns %}

Your configured rules determine which eligible activities award points and which workflows are enabled.

## Integration Steps

{% stepper %}
{% step %}

### Account setup in Middle

Your Perkville Customer Success Representative will send you an invitation to our integration platform, [Middle](https://middle.app).

Follow the link in your invitation email to Middle to complete registration and set your password.
{% endstep %}

{% step %}

### Authorize the integration

Once registered and signed into Middle, follow these steps:

1. Click on the **“HubSpot” app** in the top left corner
2. Select **“Edit Connection Details”**
3. **Custom Fields For Contacts:** If you would like to sync specific custom fields for Contacts, enter the property "name" here, one per line
4. **Custom Fields Prefix for Contact Syncs**: If you would like to sync specific custom fields for Contacts based on a prefix, enter the prefix of the properties' names
5. Click **“Launch OAuth Flow”**
6. Follow the prompts to complete authorization

{% hint style="warning" %}
Be sure to log into a HubSpot admin account when completing the OAuth flow
{% endhint %}
{% endstep %}
{% endstepper %}

## Data mapping for Perkville data

The Perkville team will need to know which Hubspot contacts need to be created or updated by the integration and which properties need to be updated. We'll need the following:

* The internal name of the property
* The data type of the property (text, number, date, or datetime)

### **Internal name**

Hubspot custom properties allow you to map non-standard data from your source app to Hubspot. Follow the instructions in the linked article to learn how to setup custom fields in your Hubspot instance:

{% embed url="<https://knowledge.hubspot.com/properties/create-and-edit-properties>" %}

The internal name can be found in your property settings or when you're creating a new property:

<figure><img src="https://docs.middle.app/middle-docs/~gitbook/image?url=https%3A%2F%2F932524191-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-Mks_UuU2atghAuA9bQz%252Fuploads%252FLYk1OBQ0cZu9LG0m9fhy%252FScreenshot%25202025-06-18%2520at%25201.03.38%25E2%2580%25AFPM.png%3Falt%3Dmedia%26token%3D94603f5e-f94b-47c2-8e41-5e736c368cab&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=8aa77853&#x26;sv=2" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
Once a property is created, the internal name cannot be edited
{% endhint %}

## Integration guides

* [Syncing Perkville leads](https://docs.perkville.com/integrations/integration-reference/hubspot/syncing-perkville-leads.md)

## FAQ

### Does the lead sync update existing contacts?

The default referral-lead workflow creates new contacts only. Other program-data workflows can update properties; agree their matching and update rules separately.

See the [HubSpot partner profile](https://partners.perkville.com/partners/hubspot) for additional integration information.

{% hint style="info" %}
**Continue reading**

Start with [Syncing Perkville leads](https://docs.perkville.com/integrations/integration-reference/hubspot/syncing-perkville-leads.md) to explore the detailed guides in this section.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.perkville.com/integrations/integration-reference/hubspot.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
