hubspot

What this skill does

## Troubleshooting

If requests fail, run `zero doctor check-connector --env-name HUBSPOT_TOKEN` or `zero doctor check-connector --url https://api.hubapi.com/crm/v3/objects/contacts --method GET`

## CRM Objects (Unified Pattern)

All CRM objects follow the same CRUD pattern at `/crm/v3/objects/{objectType}`. The `{objectType}` can be: `contacts`, `companies`, `deals`, `tickets`, `products`, `line_items`, `quotes`, `tasks`, `notes`, `emails`, `meetings`, `calls`.

> **Important:** Always specify `properties` query param to control which fields are returned. Without it, only default properties are included.

### List Objects

```bash
curl -s "https://api.hubapi.com/crm/v3/objects/contacts?limit=10&properties=firstname,lastname,email" \
  --header "Authorization: Bearer $HUBSPOT_TOKEN"
```

Params: `limit` (max 100), `after` (pagination cursor from `paging.next.after`), `properties` (comma-separated), `propertiesWithHistory`, `associations`.

### Get Object by ID

```bash
curl -s "https://api.hubapi.com/crm/v3/objects/contacts/<contact-id>?properties=firstname,lastname,email,phone,company" \
  --header "Authorization: Bearer $HUBSPOT_TOKEN"
```

### Create Object

```bash
curl -s -X POST "https://api.hubapi.com/crm/v3/objects/contacts" \
  --header "Authorization: Bearer $HUBSPOT_TOKEN" \
  --header "Content-Type: application/json" \
  -d "{\"properties\": {\"firstname\": \"Jane\", \"lastname\": \"Doe\", \"email\": \"[email protected]\", \"phone\": \"+1-555-0100\", \"company\": \"Acme Corp\"}}"
```

### Update Object

```bash
curl -s -X PATCH "https://api.hubapi.com/crm/v3/objects/contacts/<contact-id>" \
  --header "Authorization: Bearer $HUBSPOT_TOKEN" \
  --header "Content-Type: application/json" \
  -d "{\"properties\": {\"phone\": \"+1-555-0200\", \"company\": \"New Corp\"}}"
```

### Delete Object

```bash
curl -s -X DELETE "https://api.hubapi.com/crm/v3/objects/contacts/<contact-id>" \
  --header "Authorization: Bearer $HUBSPOT_TOKEN"
```

Moves to recycling bin. Can be restored within 90 days.

### Search Objects

Search supports complex filter groups with AND/OR logic.

```bash
curl -s -X POST "https://api.hubapi.com/crm/v3/objects/contacts/search" \
  --header "Authorization: Bearer $HUBSPOT_TOKEN" \
  --header "Content-Type: application/json" \
  -d "{\"filterGroups\": [{\"filters\": [{\"propertyName\": \"email\", \"operator\": \"CONTAINS_TOKEN\", \"value\": \"example.com\"}]}], \"properties\": [\"firstname\", \"lastname\", \"email\"], \"limit\": 10}"
```

Search operators: `EQ`, `NEQ`, `LT`, `LTE`, `GT`, `GTE`, `CONTAINS_TOKEN`, `NOT_CONTAINS_TOKEN`, `HAS_PROPERTY`, `NOT_HAS_PROPERTY`, `BETWEEN`.

### Batch Read

Read multiple objects by ID in a single request.

```bash
curl -s -X POST "https://api.hubapi.com/crm/v3/objects/contacts/batch/read" \
  --header "Authorization: Bearer $HUBSPOT_TOKEN" \
  --header "Content-Type: application/json" \
  -d "{\"inputs\": [{\"id\": \"<id-1>\"}, {\"id\": \"<id-2>\"}], \"properties\": [\"firstname\", \"lastname\", \"email\"]}"
```

### Batch Create

```bash
curl -s -X POST "https://api.hubapi.com/crm/v3/objects/contacts/batch/create" \
  --header "Authorization: Bearer $HUBSPOT_TOKEN" \
  --header "Content-Type: application/json" \
  -d "{\"inputs\": [{\"properties\": {\"firstname\": \"Alice\", \"email\": \"[email protected]\"}}, {\"properties\": {\"firstname\": \"Bob\", \"email\": \"[email protected]\"}}]}"
```

### Batch Update

```bash
curl -s -X POST "https://api.hubapi.com/crm/v3/objects/contacts/batch/update" \
  --header "Authorization: Bearer $HUBSPOT_TOKEN" \
  --header "Content-Type: application/json" \
  -d "{\"inputs\": [{\"id\": \"<id-1>\", \"properties\": {\"phone\": \"+1-555-0001\"}}, {\"id\": \"<id-2>\", \"properties\": {\"phone\": \"+1-555-0002\"}}]}"
```

### Merge Objects

Merge two records of the same type. The primary record survives.

```bash
curl -s -X POST "https://api.hubapi.com/crm/v3/objects/contacts/merge" \
  --header "Authorization: Bearer $HUBSPOT_TOKEN" \
  --header "Content-Type: application/json" \
  -d "{\"primaryObjectId\": \"<primary-id>\", \"objectIdToMerge\": \"<duplicate-id>\"}"
```

## Common CRM Object Examples

The pattern above works for all object types. Here are property examples for the most common ones:

### Create Company

```bash
curl -s -X POST "https://api.hubapi.com/crm/v3/objects/companies" \
  --header "Authorization: Bearer $HUBSPOT_TOKEN" \
  --header "Content-Type: application/json" \
  -d "{\"properties\": {\"name\": \"Acme Corp\", \"domain\": \"acme.com\", \"industry\": \"Technology\"}}"
```

### Create Deal

```bash
curl -s -X POST "https://api.hubapi.com/crm/v3/objects/deals" \
  --header "Authorization: Bearer $HUBSPOT_TOKEN" \
  --header "Content-Type: application/json" \
  -d "{\"properties\": {\"dealname\": \"Enterprise License\", \"amount\": \"50000\", \"dealstage\": \"appointmentscheduled\", \"pipeline\": \"default\", \"closedate\": \"2026-06-30T00:00:00.000Z\"}}"
```

### Create Ticket

```bash
curl -s -X POST "https://api.hubapi.com/crm/v3/objects/tickets" \
  --header "Authorization: Bearer $HUBSPOT_TOKEN" \
  --header "Content-Type: application/json" \
  -d "{\"properties\": {\"subject\": \"Login issue\", \"content\": \"User cannot log in after password reset\", \"hs_pipeline\": \"0\", \"hs_pipeline_stage\": \"1\"}}"
```

### Create Task

```bash
curl -s -X POST "https://api.hubapi.com/crm/v3/objects/tasks" \
  --header "Authorization: Bearer $HUBSPOT_TOKEN" \
  --header "Content-Type: application/json" \
  -d "{\"properties\": {\"hs_task_subject\": \"Follow up with client\", \"hs_task_body\": \"Discuss renewal terms\", \"hs_task_status\": \"NOT_STARTED\", \"hs_task_priority\": \"HIGH\", \"hs_timestamp\": \"2026-04-15T09:00:00.000Z\"}}"
```

### Create Note

```bash
curl -s -X POST "https://api.hubapi.com/crm/v3/objects/notes" \
  --header "Authorization: Bearer $HUBSPOT_TOKEN" \
  --header "Content-Type: application/json" \
  -d "{\"properties\": {\"hs_note_body\": \"Had a productive call. Client interested in annual plan.\", \"hs_timestamp\": \"2026-04-08T14:00:00.000Z\"}}"
```

## Associations (v4)

Associations link CRM objects together (e.g., contact → company, deal → contact).

### Create Association (Default Type)

```bash
curl -s -X PUT "https://api.hubapi.com/crm/v4/objects/contacts/<contact-id>/associations/default/companies/<company-id>" \
  --header "Authorization: Bearer $HUBSPOT_TOKEN"
```

### Create Association (Labeled)

```bash
curl -s -X PUT "https://api.hubapi.com/crm/v4/objects/contacts/<contact-id>/associations/companies/<company-id>" \
  --header "Authorization: Bearer $HUBSPOT_TOKEN" \
  --header "Content-Type: application/json" \
  -d "[{\"associationCategory\": \"HUBSPOT_DEFINED\", \"associationTypeId\": 1}]"
```

Common association type IDs: `1` (contact→company), `3` (deal→contact), `5` (deal→company), `27` (ticket→contact), `339` (ticket→company).

### List Associations

```bash
curl -s "https://api.hubapi.com/crm/v4/objects/contacts/<contact-id>/associations/companies" \
  --header "Authorization: Bearer $HUBSPOT_TOKEN"
```

### Remove Association

```bash
curl -s -X DELETE "https://api.hubapi.com/crm/v4/objects/contacts/<contact-id>/associations/companies/<company-id>" \
  --header "Authorization: Bearer $HUBSPOT_TOKEN"
```

### Batch Read Associations

```bash
curl -s -X POST "https://api.hubapi.com/crm/v4/associations/contacts/companies/batch/read" \
  --header "Authorization: Bearer $HUBSPOT_TOKEN" \
  --header "Content-Type: application/json" \
  -d "{\"inputs\": [{\"id\": \"<contact-id-1>\"}, {\"id\": \"<contact-id-2>\"}]}"
```

## Pipelines

Pipelines define workflow stages for deals and tickets.

### List Pipelines

```bash
curl -s "https://api.hubapi.com/crm/v3/pipelines/deals" \
  --header "Authorization: Bearer $HUBSPOT_TOKEN"
```

Replace `deals` with `tickets` or other object types that support pipelines.

### Get Pipeline Stages

```bash
curl -s "https://api.hubapi.com/crm/v3/pipelines/dea