crm-hubspot

README.md

---
name: crm-hubspot
description: Create and update HubSpot contacts, deals, and companies; search and associate records. Use when the agent should log leads, update contact lifecycle, sync pipeline results, or look up CRM data in HubSpot.
credentials:
  - HUBSPOT_ACCESS_TOKEN
metadata:
  sulala:
    emoji: "🟠"
    requires:
      bins:
        - node
---

# CRM (HubSpot)

Create, update, search, and associate **contacts**, **deals**, and **companies** in HubSpot. The agent uses the **exec** tool with **skill_id: "crm-hubspot"** so `HUBSPOT_ACCESS_TOKEN` is injected from skill config.

## Contents

| Feature | Script | Description |
|--------|--------|-------------|
| **Contacts** | | |
| Create contact | `create_contact.js` | Create a contact with properties (email, firstname, lastname, company, lifecyclestage, etc.). |
| Update contact | `update_contact.js` | Update a contact by ID. |
| Search contacts | `search_contact.js` | Search contacts by email or other filters (returns IDs and properties). |
| Get contact | `get_contact.js` | Get one contact by ID. |
| **Deals** | | |
| Create deal | `create_deal.js` | Create a deal (dealname, pipeline, dealstage, amount). |
| Update deal | `update_deal.js` | Update a deal by ID. |
| Search deals | `search_deal.js` | Search deals by name or other filters. |
| Get deal | `get_deal.js` | Get one deal by ID. |
| **Companies** | | |
| Create company | `create_company.js` | Create a company (name, domain, etc.). |
| Update company | `update_company.js` | Update a company by ID. |
| **Associations** | | |
| Associate contact to deal | `associate_contact_deal.js` | Link a contact to a deal. |
| Associate contact to company | `associate_contact_company.js` | Link a contact to a company (e.g. primary company). |

## Install

Run **sulala skill install crm-hubspot** or install from the dashboard **Skills** page. This installs the latest version (currently v2.0.0); you can pin a specific version in your skill config if needed.

## Prerequisites

1. Add the **crm-hubspot** skill to the agent (e.g. the CRM Agent in a sales pipeline).
2. Configure **HUBSPOT_ACCESS_TOKEN** in the skill (Skills → crm-hubspot → Configure).

## Setup

1. **HubSpot account** — Sign in at [hubspot.com](https://www.hubspot.com).
2. **Private app** — Settings → Integrations → Private Apps → Create a private app. Name it (e.g. "Agent CRM"). Under Scopes, add:
   - **crm.objects.contacts.read**, **crm.objects.contacts.write**
   - **crm.objects.deals.read**, **crm.objects.deals.write**
   - **crm.objects.companies.read**, **crm.objects.companies.write** (for company and association features)
   Create the app and copy the **Access token**.
3. **Skill config** — Paste the token as **HUBSPOT_ACCESS_TOKEN** in Skills → crm-hubspot → Configure.

## Create a contact

Use **exec** with **skill_id: "crm-hubspot"**. The first argument is a JSON object of HubSpot contact **properties** (e.g. `email`, `firstname`, `lastname`, `phone`, `company`, `lifecyclestage`).

**Example:**

- **skill_id:** `crm-hubspot`
- **command:** `node ./scripts/create_contact.js '{"email":"contact@acme.com","firstname":"Jane","lastname":"Doe","company":"Acme Inc","lifecyclestage":"lead"}'`

At least one of `email`, `firstname`, or `lastname` is required. Use internal property names (e.g. `lifecyclestage`, not the label).

## Update a contact

Pass the contact **record ID** (numeric) and a JSON object of properties to update.

**Example:**

- **command:** `node ./scripts/update_contact.js 12345678 '{"lifecyclestage":"opportunity","notes_last_updated":"2025-03-16"}'`

## Create a deal

Pass a JSON object of deal **properties** (e.g. `dealname`, `pipeline`, `dealstage`, `amount`). Pipeline and dealstage depend on your HubSpot pipeline configuration.

**Example:**

- **command:** `node ./scripts/create_deal.js '{"dealname":"Acme - Q2","pipeline":"default","dealstage":"appointmentscheduled","amount":"5000"}'`

## Update a deal

Pass the deal **record ID** and a JSON object of properties to update.

**Example:**

- **command:** `node ./scripts/update_deal.js 98765432 '{"dealstage":"closedwon"}'`

## Search contacts

Search contacts by **email** (or a custom filter JSON). Returns matching contacts with IDs and requested properties.

**Example (by email):**

- **command:** `node ./scripts/search_contact.js '{"email":"contact@acme.com"}'`

Optional: pass a second argument with comma-separated properties to return (default includes `email`, `firstname`, `lastname`, `company`, `lifecyclestage`).

## Get contact by ID

Fetch one contact by numeric **record ID**.

**Example:**

- **command:** `node ./scripts/get_contact.js 12345678`

## Search deals

Search deals by **dealname** (or a custom filter JSON). Returns matching deals with IDs and properties.

**Example:**

- **command:** `node ./scripts/search_deal.js '{"dealname":"Acme"}'`

## Get deal by ID

Fetch one deal by numeric **record ID**.

**Example:**

- **command:** `node ./scripts/get_deal.js 98765432`

## Create a company

Pass a JSON object of company **properties** (e.g. `name`, `domain`, `industry`, `phone`).

**Example:**

- **command:** `node ./scripts/create_company.js '{"name":"Acme Inc","domain":"acme.com"}'`

## Update a company

Pass the company **record ID** and a JSON object of properties to update.

**Example:**

- **command:** `node ./scripts/update_company.js 55555555 '{"name":"Acme Corp"}'`

## Associate contact to deal

Link a contact to a deal (e.g. after creating both). Pass **contact ID** and **deal ID**.

**Example:**

- **command:** `node ./scripts/associate_contact_deal.js 12345678 98765432`

## Associate contact to company

Link a contact to a company (e.g. set primary company). Pass **contact ID** and **company ID**.

**Example:**

- **command:** `node ./scripts/associate_contact_company.js 12345678 55555555`

## Pipeline use (CRM Agent)

The CRM Agent receives the previous node’s output (e.g. follow-up status). The agent should parse it, then call **exec** with **skill_id: "crm-hubspot"** to create or update contacts and deals. Return a short summary of what was written to HubSpot.