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

# HubSpot

> Marketing automation and contact management

## Overview

HubSpot integration synchronizes member data and enables marketing automation based on membership activities.

## Features

| Feature           | Description                                       |
| ----------------- | ------------------------------------------------- |
| Contact Sync      | Sync members as HubSpot contacts                  |
| Company Sync      | Sync organizations as HubSpot companies           |
| Activity Tracking | Log membership activities                         |
| List Management   | Segment members in HubSpot lists                  |
| Workflow Triggers | Trigger HubSpot workflows from MemberPulse events |

## Configuration

### Prerequisites

1. HubSpot account with Marketing Hub
2. Private App created in HubSpot
3. API key with required scopes

#### Acceptance Criteria

##### Frontend

* [ ] Prerequisites workflow is implemented in the UI as described.

##### Backend / API

* [ ] Backend behavior supports Prerequisites as documented.

##### Permissions

* [ ] Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

##### Business Rules

* [ ] All business rules for this feature are enforced.

##### Error Handling

* [ ] Error states return clear messages and appropriate HTTP status codes.

### Environment Variables

```bash theme={null}
HUBSPOT_PORTAL_ID=xxxxxxxxxxxx
HUBSPOT_API_KEY=xxxxxxxxxxxx
```

#### Acceptance Criteria

##### Frontend

* [ ] Environment Variables workflow is implemented in the UI as described.

##### Backend / API

* [ ] Backend behavior supports Environment Variables as documented.

##### Permissions

* [ ] Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

##### Business Rules

* [ ] All business rules for this feature are enforced.

##### Error Handling

* [ ] Error states return clear messages and appropriate HTTP status codes.

### Platform Settings

Navigate to **Client Portal > Settings > Integrations > HubSpot**

| Setting        | Type   | Required | Description                          |
| -------------- | ------ | -------- | ------------------------------------ |
| Portal ID      | Text   | Yes      | HubSpot portal/account ID            |
| API Key        | Secret | Yes      | Private app API key                  |
| Sync Contacts  | Toggle | No       | Auto-sync members to contacts        |
| Sync Companies | Toggle | No       | Auto-sync organizations to companies |

#### Acceptance Criteria

##### Frontend

* [ ] Platform Settings workflow is implemented in the UI as described.

##### Backend / API

* [ ] Backend behavior supports Platform Settings as documented.

##### Permissions

* [ ] Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

##### Business Rules

* [ ] All business rules for this feature are enforced.

##### Error Handling

* [ ] Error states return clear messages and appropriate HTTP status codes.

## Sync Operations

| Operation  | Direction             | Description            |
| ---------- | --------------------- | ---------------------- |
| Contacts   | MemberPulse → HubSpot | Sync member data       |
| Companies  | MemberPulse → HubSpot | Sync organization data |
| Activities | MemberPulse → HubSpot | Log membership events  |

## Tagging & Automation (Predefined Tags)

MemberPulse emits a small, **hardcoded** set of tags to keep HubSpot automation predictable.

* Tag catalog: [`CRM Tag`](/entities/integration/crm-tag)
* Sync log/audit trail: [`CRM Sync Record`](/entities/integration/crm-sync-record)

Typical flows:

* **Membership**: apply membership status tags (active/expiring/expired, upgraded, downgrade scheduled)
* **Events**: apply **pre-event** tag on registration and **post-event** tags on attendance/no-show
* **Courses**: apply tag on enrollment and completion

How tags map into HubSpot:

* Tags can be written to a Contact property and/or used to drive HubSpot Lists and Workflows.

## Support Ticket Notes

When enabled, support ticket activity is logged back to the Contact as a HubSpot engagement:

* Minimum payload: ticket number + status + link back to MemberPulse

## Troubleshooting

For HubSpot integration issues, see the [Admin Troubleshooting Guide](/admin/hubspot-troubleshooting).

#### Acceptance Criteria

##### Frontend

* [ ] UI provides configuration controls and status/health indicators for this integration.

##### Backend / API

* [ ] Integration can be connected, configured, and exercised end-to-end (auth + sync/webhooks).

##### Permissions

* [ ] Only `ROLE_CLIENT_ADMIN` (or equivalent) can configure the integration.

##### Business Rules

* [ ] Data sync respects tenant isolation and mapping rules.

##### Error Handling

* [ ] Auth and sync failures are surfaced with actionable messages and retry behavior.