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

# Sync Hint Patients to HubSpot Contacts

> Set up the Hint → HubSpot template so each patient's contact and membership details stay current in HubSpot.

The **Hint Patient to Hubspot Contact Sync** workflow keeps HubSpot contacts in sync with patients in Hint. When a patient changes in Hint, Morf creates or updates the matching HubSpot contact with their name, email, phone and address. It also writes their membership details to six custom properties. You can use those properties to build lists, segments and marketing emails.

![Hint sends a patient event to the Morf workflow, which updates the HubSpot contact's built-in properties and six custom Hint Membership properties](https://mintcdn.com/morfhealth/Onefm6hnxiH-hnQE/images/hint_hubspot_sync_light.svg?fit=max\&auto=format\&n=Onefm6hnxiH-hnQE\&q=85\&s=8705251ed4cbc761877983e2106d386b)

The template is already in your list of workflows. Setting it up takes about 10 minutes and has four steps:

> [card] [1. Install the Morf app](#1-install-the-morf-app-from-the-hint-marketplace)
>
> Add Morf from the Hint marketplace so Morf receives patient updates.

> [card] [2. Connect HubSpot](#2-connect-your-hubspot-account-to-morf)
>
> Create a HubSpot private app and add its access token to Morf.

> [card] [3. Create custom properties](#3-create-the-custom-properties-in-hubspot)
>
> Add the six Hint Membership properties with Breeze or by hand.

> [card] [4. Publish the workflow](#4-publish-the-workflow)
>
> Turn on the template and check a test patient syncs.

## Before you start

* **Hint:** You need to be an admin in Hint so you can install marketplace apps.
* **HubSpot:** You need to be a Super Admin, or have permission to create private apps and to **Edit property settings** for contacts.
* **Compliance:** The sync sends patient membership information to HubSpot. Check with your compliance lead that your HubSpot account is approved for this data.

## 1. Install the Morf app from the Hint marketplace

Installing the Morf app lets Morf receive patient updates from Hint.

1. Sign in to Hint as an admin.
2. Open the Hint marketplace and search for **Morf**.
3. Click **Install**, select the correct org in Morf and approve the requested permissions.

When the install finishes, Hint appears as a connected integration on the **Integrations** page of your Morf dashboard.

## 2. Connect your HubSpot account to Morf

Morf writes to HubSpot using the access token from a HubSpot private app.

### Create a private app in HubSpot

1. In HubSpot, click the **Settings** gear icon in the top navigation bar.
2. In the left sidebar, go to **Integrations → Private Apps**, then click **Create a private app**.
3. Name the app **Morf Health**.
4. Open the **Scopes** tab and add:
   * `crm.objects.contacts.read`
   * `crm.objects.contacts.write`
   * `crm.schemas.contacts.read`
5. Click **Create app**, then copy the access token from the **Auth** tab.

For more detail, see HubSpot's guide to [creating a private app](https://developers.hubspot.com/docs/guides/apps/private-apps/overview#create-a-private-app).

### Add the token to Morf

1. In the Morf dashboard, go to the **Integrations** page and click **+ Integration** in the top right.
2. Select **Hubspot App Access Token** and click **Continue**.
3. Paste the access token and click **Connect**.

> [!NOTE]
>
> If you use separate staging and production organizations in Morf, connect the token in each one.

## 3. Create the custom properties in HubSpot

The standard fields (name, email, phone, address, city, state and zip) go into HubSpot's built-in contact properties, so you don't need to set those up. You do need to create six custom contact properties for the membership details.

You can create them with HubSpot's Breeze assistant, or by hand. Either way, check the result against the [property reference](#property-reference) before you publish.

> [!WARNING]
>
> The sync writes to each property's **internal name**, not its label. The internal names must match the table below exactly. HubSpot doesn't let you change an internal name after the property is created. If one is wrong, delete the property and create it again.

### Property reference

| Label (suggested) | Internal name (must match) | Field type | What it holds |
| - | - | - | - |
| Hint Patient ID | `hint_id` | Single-line text | The patient's ID in Hint. Used to match records. |
| Membership Status | `membership_status` | Dropdown select | The patient's overall membership status in Hint |
| Enrollment Status | `enrollment_status` | Dropdown select | Enrollment status of the patient's current membership |
| Plan Name | `plan_name` | Single-line text | Name of the patient's membership plan |
| Membership Start Date | `membership_start_date` | Date picker | The date the current membership started |
| Past Due Amount | `past_due_amount` | Number (currency format) | Balance past due on the patient's account, in dollars |

The two dropdowns need these options. The internal value of each option must exactly match the lowercase value Hint sends, or HubSpot rejects the update for that contact. You can use any label you like.

| Property | Internal values |
| - | - |
| `membership_status` | `active`, `pending`, `unconfirmed`, `unpaid`, `inactive`, `archived` |
| `enrollment_status` | `active`, `pending`, `unconfirmed`, `inactive`, `ended` |

> [tab] Use Breeze assistant
>
> 1. In HubSpot, open **Breeze** from the top navigation bar.
> 2. Copy the prompt below, paste it into Breeze and send it.
> 3. Review what Breeze plans to create and confirm.
> 4. Go to **Settings → Data Management → Properties**, filter by the **Hint Membership** group, and check each internal name and dropdown value against the [property reference](#property-reference). Fix anything that doesn't match using the manual steps.
>
> ```text theme={null}
> Create a contact property group called "Hint Membership". Then create the following six contact properties in that group. Use the internal names exactly as written, all lowercase with underscores. Do not let HubSpot generate its own internal names.
>
> 1. Label "Hint Patient ID", internal name hint_id, field type single-line text. Require unique values.
> 2. Label "Membership Status", internal name membership_status, field type dropdown select, with these options (label → internal value): Active → active, Pending → pending, Unconfirmed → unconfirmed, Unpaid → unpaid, Inactive → inactive, Archived → archived.
> 3. Label "Enrollment Status", internal name enrollment_status, field type dropdown select, with these options (label → internal value): Active → active, Pending → pending, Unconfirmed → unconfirmed, Inactive → inactive, Ended → ended.
> 4. Label "Plan Name", internal name plan_name, field type single-line text.
> 5. Label "Membership Start Date", internal name membership_start_date, field type date picker.
> 6. Label "Past Due Amount", internal name past_due_amount, field type number, formatted as currency (USD).
>
> Give each property the description "Synced from Hint. Do not edit manually."
>
> When you're done, list each property with its label, internal name, field type and dropdown options so I can check them.
> ```

> [tab] Create manually
>
> **Create a property group (recommended).** A group keeps the Hint fields together on the contact record.
>
> 1. Click the **Settings** gear icon in the top navigation bar.
> 2. In the left sidebar, go to **Data Management → Properties**.
> 3. Make sure **Contact properties** is selected, then open the **Groups** tab.
> 4. Click **Create group**, name it **Hint Membership**, and save.
>
> **Create each property.** Repeat these steps for each of the six properties in the [property reference](#property-reference).
>
> 1. Go to **Settings → Data Management → Properties**, with **Contact properties** selected.
> 2. Click **Create property** in the top right.
> 3. Set **Object type** to **Contact** and **Group** to **Hint Membership**.
> 4. Enter the **Property label** from the table.
> 5. Set the internal name before you go any further. Click the code icon (`</>`) next to the label to show the internal name HubSpot generated, and replace it with the exact value from the table. For example, HubSpot suggests `hint_patient_id` for "Hint Patient ID", and you need to change it to `hint_id`.
> 6. Optionally add a description, such as "Synced from Hint. Do not edit manually."
> 7. Click **Next** and pick the **Field type** from the table. Then follow the extra setup for that type:
>    * **Hint Patient ID:** Turn on **Require unique values for this property**. This stops two contacts from sharing the same Hint ID.
>    * **Membership Status** and **Enrollment Status:** Add the dropdown options listed above.
>    * **Past Due Amount:** Set the number format to **Currency (USD)**.
>    * **Membership Start Date:** No extra settings.
> 8. Click **Create**.
>
> Once all six are created, filter the property list by the **Hint Membership** group and check the internal names against the table.

> [!TIP]
>
> Use the status values to build active lists, such as "Active members", "Pending sign-ups to nudge" and "Inactive members for win-back".

## 4. Publish the workflow

1. In the Morf dashboard, open **Workflows** and select **\[Template] Hint Patient to Hubspot Contact Sync**.
2. Open the **Build** tab. Check that the HubSpot actions show your connected HubSpot account.
3. Click **Publish**.

The workflow now runs every time a patient is created or updated in Hint. See [workflow statuses](https://docs.morf.health/docs/morf_dashboard/workflows.md#what-are-the-different-workflow-statuses) for how to pause it later.

### Check that it works

1. Update a test patient in Hint.
2. Open that contact in HubSpot. The Hint Membership fields should fill in within a few minutes.
3. Open the contact's **Actions → View property history** to confirm the values came from the integration.

You can also follow each run in Morf on the [Monitoring](https://docs.morf.health/docs/morf_dashboard/monitoring.md) page.

## Sync more Hint data (optional)

The template sends a standard set of fields, but Hint holds much more about each patient. If you'd like to sync additional data to hubspot, you can create a HubSpot custom contact property for it, then map it in the workflow.

### Choose the Hint field

The [Hint Patient event](https://docs.morf.health/docs/events/payloads/hint_health/patient.md#payload-field-details) lists every field you can use. Each field shows the expression you'll use in the workflow. Some common additions:

| Hint field | Expression | Suggested HubSpot field type |
| - | - | - |
| Preferred language | `preferred_language` | Single-line text |
| Pronouns | `pronouns` | Single-line text |
| Lead source | `lead_source.name` | Single-line text |
| Home location | `location.name` | Single-line text |
| Employer or sponsor | `company.name` | Single-line text |

> [!WARNING]
>
> Some Hint fields are protected health information, such as insurance details, date of birth and sex. Check with your compliance lead before you send any new field to HubSpot.

### Create the property in HubSpot

Create a contact property with the same steps as in [step 3](#3-create-the-custom-properties-in-hubspot), and put it in the **Hint Membership** group. You choose the label and internal name. Write the internal name down, because you'll pick it in the workflow in the next step.

To use Breeze, adapt this prompt:

```text theme={null}
Create a contact property in the "Hint Membership" group with the label "Preferred Language", internal name preferred_language, field type single-line text, and the description "Synced from Hint. Do not edit manually." Then show me its label, internal name and field type.
```

If you pick a dropdown field type, each option's internal value must exactly match the value Hint sends. If a value Hint sends has no matching option, HubSpot rejects the update for that contact. When you aren't sure which values Hint uses, use single-line text instead.

### Map the field in the workflow

1. In the Morf dashboard, open **Workflows** and select **\[Template] Hint Patient to Hubspot Contact Sync**.
2. Open the **Build** tab and click the HubSpot **Create or Update Contact** action.
3. Under **Properties**, add a row.
4. Pick your new HubSpot property from the list. If it isn't there, check that you created it as a contact property.
5. Enter the expression for the Hint field, such as `preferred_language`.
6. Click **Publish**.

For dates and numbers, copy the pattern the template already uses for **Membership Start Date** or **Past Due Amount**. For anything more complex, see [Common Expression Language](https://docs.morf.health/docs/libraries/cel.md) or contact Morf support.

Update a test patient in Hint to check the new field fills in, just as you did in [Check that it works](#check-that-it-works).

## Troubleshooting

| Problem | Likely cause | Fix |
| - | - | - |
| A field stays blank | The internal name doesn't match | Compare against the [property reference](#property-reference). If it's wrong, delete the property and create it again with the correct internal name. |
| The status field is blank but the other fields synced | A dropdown internal value is missing or has a typo | Add or correct the option under the property's field settings. |
| The sync reports a duplicate error | Two contacts have the same Hint Patient ID | Merge the duplicate contacts in HubSpot. |
| Past Due Amount looks 100× too large | The value is being written in cents | Contact Morf support. |
| The workflow doesn't run when a patient changes | The Morf app isn't installed in Hint, or the workflow isn't published | Check the Hint integration on the Morf **Integrations** page and confirm the workflow status is **Published**. |


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