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

# HubSpot Connector Tools

> Read and update HubSpot CRM records, including irreversible contact and company merges.

## Overview

<Note>
  Before using this tool group, save a HubSpot connection in **Config -> Connections**. See [HubSpot](/docs/Setup/HubSpot) for Service Key setup, required scopes, and merge opt-in settings.

  Merges are **permanent** — HubSpot redirects both input record ids to the resulting record. `REQUEST_MERGE_APPROVAL` returns `review_required`; follow the [shared CRM merge workflow](/docs/Genesis-API/API-Reference#crm-merge-endpoints) before execution.
</Note>

### Tool Name

```json theme={null}
hubspot_connector_tools
```

### Purpose

The **hubspot\_connector\_tools** group integrates Genesis with HubSpot CRM. Search and read contacts, companies, deals, and tickets; inspect properties and associations; create, update, and batch-upsert records; and merge duplicate **contacts** and **companies**.

#### Functions Available

1. **`hubspot_connector`**: Bounded HubSpot reads, record mutations, and merge preview / request / execute actions.

## Input Parameters

### `hubspot_connector`

**Parameters**

| **Name** | **Definition** | **Format** | **Default** |
| - | - | :-: | :-: |
| **action** | Operation to perform. Supported: `TEST_CONNECTION`, `SEARCH_OBJECTS`, `GET_OBJECT`, `LIST_PROPERTIES`, `LIST_ASSOCIATIONS`, `CREATE_OBJECT`, `UPDATE_OBJECT`, `BATCH_UPSERT`, `PREVIEW_MERGE`, `REQUEST_MERGE_APPROVAL`, `EXECUTE_APPROVED_MERGE`, `GET_MERGE_APPROVAL`. | String (required) | none |
| **connection** | HubSpot connection name such as `hubspot.production`. Merge actions require an explicit connection; other actions may use the effective default. | String | none |
| **object\_type** | HubSpot CRM object type, such as `contacts` or `companies`. Merge actions support only `contacts` and `companies`. | String | none |
| **record\_id** | HubSpot CRM object id for `GET_OBJECT`, `UPDATE_OBJECT`, or `LIST_ASSOCIATIONS`. | String | none |
| **filter\_groups** | HubSpot `filterGroups` for `SEARCH_OBJECTS`. | Array of objects | none |
| **properties** | Properties to return or include in a merge preview projection. | Array of strings | none |
| **associations** | HubSpot association payload for `CREATE_OBJECT`. | Array of objects | none |
| **to\_object\_type** | Destination HubSpot object type for `LIST_ASSOCIATIONS`. | String | none |
| **data** | Properties object for `CREATE_OBJECT` or `UPDATE_OBJECT`. | Object | none |
| **inputs** | HubSpot batch upsert input objects for `BATCH_UPSERT` (maximum `100` per request). | Array of objects | none |
| **limit** | Maximum results for `SEARCH_OBJECTS` or `LIST_ASSOCIATIONS`. | Integer | none |
| **after** | HubSpot paging cursor for `SEARCH_OBJECTS` or `LIST_ASSOCIATIONS`. | String | none |
| **survivor\_id** | First numeric HubSpot input id, sent as `primaryObjectId`. HubSpot determines the resulting record id and redirects both input ids to it. | String | none |
| **loser\_ids** | Exactly one second numeric HubSpot input id to merge with `survivor_id`. | Array of strings | none |
| **expected\_digest** | Optional preview digest that `REQUEST_MERGE_APPROVAL` must reproduce. | String | none |
| **ttl\_seconds** | Lifetime of a pending HubSpot merge approval in seconds. | Integer | `3600` |
| **approval\_id** | Action Review proposal ID returned by `REQUEST_MERGE_APPROVAL`, required by `EXECUTE_APPROVED_MERGE` or `GET_MERGE_APPROVAL`. | String | none |

<Note>
  **Read-only connections:** When the connection locator sets `read_only` to a truthy value, or `access_intent` to `read` or `read_only`, write and merge actions are refused.

  **Merge opt-in:** `PREVIEW_MERGE`, `REQUEST_MERGE_APPROVAL`, and `EXECUTE_APPROVED_MERGE` require `merge_enabled` on the connection locator and a valid `merge_survivorship_policy` JSON object with `version` and `preview_fields`. See [HubSpot](/docs/Setup/HubSpot#approval-gated-merge).

  HubSpot executions follow the shared [CRM merge API outcome contract](/docs/Genesis-API/API-Reference#crm-merge-endpoints).

  **Object allowlists:** Genesis can read `contacts`, `companies`, `deals`, and `tickets` by default, and can create, update, or merge `contacts` and `companies`. An administrator can extend allowed object types through the `hubspot.extra_objects` App Config setting.

  **Deletes unavailable:** Archive and delete actions are not exposed through this tool group.
</Note>

<Warning>
  **Merge workflow:** Follow the [shared CRM merge workflow](/docs/Genesis-API/API-Reference#crm-merge-endpoints).
</Warning>

HubSpot merges cannot be undone and accept exactly one loser. If a request times
out or transport fails, reconcile HubSpot state before retrying.

**Example — search contacts**

```python theme={null}
hubspot_connector(
    action="SEARCH_OBJECTS",
    connection="hubspot.production",
    object_type="contacts",
    filter_groups=[
        {
            "filters": [
                {"propertyName": "email", "operator": "EQ", "value": "alex@example.com"},
            ],
        },
    ],
    properties=["email", "firstname", "lastname"],
    limit=10,
)
```

**Example — merge preview**

```python theme={null}
hubspot_connector(
    action="PREVIEW_MERGE",
    connection="hubspot.production",
    object_type="contacts",
    survivor_id="101",
    loser_ids=["202"],
)
```

## Use Cases

1. **Inspect CRM data** — `SEARCH_OBJECTS`, `GET_OBJECT`, or `LIST_PROPERTIES` when a user asks about HubSpot contacts, companies, deals, or tickets.
2. **Update a record** — `UPDATE_OBJECT` or `BATCH_UPSERT` when a workflow should write back to HubSpot.
3. **Duplicate review** — `PREVIEW_MERGE` to show what a contact or company merge would do before any write.
4. **Governed merge** — Follow the shared CRM merge workflow.

## Related pages

* [HubSpot](/docs/Setup/HubSpot)
* [Connections](/docs/Setup/Connections)
* [Salesforce Connector Tools](/docs/Genbot-Toolkit/Salesforce-Connector-Tools)
* [CRM merge endpoints](/docs/Genesis-API/API-Reference#crm-merge-endpoints)