AgentSkillsCN

hubspot

HubSpot CRM API 与托管 OAuth 集成。支持管理联系人、公司、交易与关联关系。当用户希望创建或更新 CRM 记录、搜索联系人，或与 HubSpot 同步数据时，可使用此技能。对于其他第三方应用，请使用 API 网关技能（https://clawhub.ai/byungkyu/api-gateway）。

SKILL.md
--- frontmatter
name: hubspot
description: |
  HubSpot CRM API integration with managed OAuth. Manage contacts, companies, deals, and associations. Use this skill when users want to create or update CRM records, search contacts, or sync data with HubSpot. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).
compatibility: Requires network access and valid Maton API key
metadata:
  author: maton
  version: "1.0"

HubSpot

Access the HubSpot CRM API with managed OAuth authentication. Create and manage contacts, companies, deals, and their associations.

Quick Start

bash
# List contacts
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/hubspot/crm/v3/objects/contacts?limit=10&properties=email,firstname,lastname')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Base URL

code
https://gateway.maton.ai/hubspot/{native-api-path}

Replace {native-api-path} with the actual HubSpot API endpoint path. The gateway proxies requests to api.hubapi.com and automatically injects your OAuth token.

Authentication

All requests require the Maton API key in the Authorization header:

code
Authorization: Bearer $MATON_API_KEY

Environment Variable: Set your API key as MATON_API_KEY:

bash
export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

  1. •Sign in or create an account at maton.ai
  2. •Go to maton.ai/settings
  3. •Copy your API key

Connection Management

Manage your HubSpot OAuth connections at https://ctrl.maton.ai.

List Connections

bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=hubspot&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Create Connection

bash
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'hubspot'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Get Connection

bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

json
{
  "connection": {
    "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
    "status": "ACTIVE",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "last_updated_time": "2026-01-31T20:03:32.593153Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "hubspot",
    "metadata": {}
  }
}

Open the returned url in a browser to complete OAuth authorization.

Delete Connection

bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Specifying Connection

If you have multiple HubSpot connections, specify which one to use with the Maton-Connection header:

bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/hubspot/crm/v3/objects/contacts')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

If omitted, the gateway uses the default (oldest) active connection.

API Reference

Contacts

List Contacts

bash
GET /hubspot/crm/v3/objects/contacts?limit=100&properties=email,firstname,lastname,phone

With pagination:

bash
GET /hubspot/crm/v3/objects/contacts?limit=100&properties=email,firstname&after={cursor}

Get Contact

bash
GET /hubspot/crm/v3/objects/contacts/{contactId}?properties=email,firstname,lastname

Create Contact

bash
POST /hubspot/crm/v3/objects/contacts
Content-Type: application/json

{
  "properties": {
    "email": "john@example.com",
    "firstname": "John",
    "lastname": "Doe",
    "phone": "+1234567890"
  }
}

Update Contact

bash
PATCH /hubspot/crm/v3/objects/contacts/{contactId}
Content-Type: application/json

{
  "properties": {
    "phone": "+0987654321"
  }
}

Delete Contact

bash
DELETE /hubspot/crm/v3/objects/contacts/{contactId}

Search Contacts

bash
POST /hubspot/crm/v3/objects/contacts/search
Content-Type: application/json

{
  "filterGroups": [{
    "filters": [{
      "propertyName": "email",
      "operator": "EQ",
      "value": "john@example.com"
    }]
  }],
  "properties": ["email", "firstname", "lastname"]
}

Companies

List Companies

bash
GET /hubspot/crm/v3/objects/companies?limit=100&properties=name,domain,industry

Get Company

bash
GET /hubspot/crm/v3/objects/companies/{companyId}?properties=name,domain,industry

Create Company

bash
POST /hubspot/crm/v3/objects/companies
Content-Type: application/json

{
  "properties": {
    "name": "Acme Corp",
    "domain": "acme.com",
    "industry": "COMPUTER_SOFTWARE"
  }
}

Note: The industry property requires specific enum values (e.g., COMPUTER_SOFTWARE, FINANCE, HEALTHCARE). Use the List Properties endpoint to get valid values.

Update Company

bash
PATCH /hubspot/crm/v3/objects/companies/{companyId}
Content-Type: application/json

{
  "properties": {
    "industry": "COMPUTER_SOFTWARE",
    "numberofemployees": "50"
  }
}

Delete Company

bash
DELETE /hubspot/crm/v3/objects/companies/{companyId}

Search Companies

bash
POST /hubspot/crm/v3/objects/companies/search
Content-Type: application/json

{
  "filterGroups": [{
    "filters": [{
      "propertyName": "domain",
      "operator": "CONTAINS_TOKEN",
      "value": "*"
    }]
  }],
  "properties": ["name", "domain"],
  "limit": 10
}

Deals

List Deals

bash
GET /hubspot/crm/v3/objects/deals?limit=100&properties=dealname,amount,dealstage

Get Deal

bash
GET /hubspot/crm/v3/objects/deals/{dealId}?properties=dealname,amount,dealstage

Create Deal

bash
POST /hubspot/crm/v3/objects/deals
Content-Type: application/json

{
  "properties": {
    "dealname": "New Deal",
    "amount": "10000",
    "dealstage": "appointmentscheduled"
  }
}

Update Deal

bash
PATCH /hubspot/crm/v3/objects/deals/{dealId}
Content-Type: application/json

{
  "properties": {
    "amount": "15000",
    "dealstage": "qualifiedtobuy"
  }
}

Delete Deal

bash
DELETE /hubspot/crm/v3/objects/deals/{dealId}

Associations (v4 API)

Associate Objects

bash
PUT /hubspot/crm/v4/objects/{fromObjectType}/{fromObjectId}/associations/{toObjectType}/{toObjectId}
Content-Type: application/json

[{"associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 279}]

Common association type IDs:

  • •279 - Contact to Company
  • •3 - Deal to Contact
  • •341 - Deal to Company

List Associations

bash
GET /hubspot/crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}

Batch Operations

Batch Read

bash
POST /hubspot/crm/v3/objects/{objectType}/batch/read
Content-Type: application/json

{
  "properties": ["email", "firstname"],
  "inputs": [{"id": "123"}, {"id": "456"}]
}

Batch Create

bash
POST /hubspot/crm/v3/objects/{objectType}/batch/create
Content-Type: application/json

{
  "inputs": [
    {"properties": {"email": "one@example.com", "firstname": "One"}},
    {"properties": {"email": "two@example.com", "firstname": "Two"}}
  ]
}

Batch Update

bash
POST /hubspot/crm/v3/objects/{objectType}/batch/update
Content-Type: application/json

{
  "inputs": [
    {"id": "123", "properties": {"firstname": "Updated"}},
    {"id": "456", "properties": {"firstname": "Also Updated"}}
  ]
}

Batch Archive

bash
POST /hubspot/crm/v3/objects/{objectType}/batch/archive
Content-Type: application/json

{
  "inputs": [{"id": "123"}, {"id": "456"}]
}

Properties

List Properties

bash
GET /hubspot/crm/v3/properties/{objectType}

Search Operators

  • •EQ - Equal to
  • •NEQ - Not equal to
  • •LT / LTE - Less than / Less than or equal
  • •GT / GTE - Greater than / Greater than or equal
  • •CONTAINS_TOKEN - Contains token
  • •NOT_CONTAINS_TOKEN - Does not contain token

Pagination

List endpoints return a paging.next.after cursor:

json
{
  "results": [...],
  "paging": {
    "next": {
      "after": "12345"
    }
  }
}

Use the after query parameter to fetch the next page:

bash
GET /hubspot/crm/v3/objects/contacts?limit=100&after=12345

Code Examples

JavaScript

javascript
const response = await fetch('https://gateway.maton.ai/hubspot/crm/v3/objects/contacts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.MATON_API_KEY}`
  },
  body: JSON.stringify({
    properties: { email: 'john@example.com', firstname: 'John' }
  })
});

Python

python
import os
import requests

response = requests.post(
    'https://gateway.maton.ai/hubspot/crm/v3/objects/contacts',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    json={'properties': {'email': 'john@example.com', 'firstname': 'John'}}
)

Notes

  • •Batch operations support up to 100 records per request
  • •Archive/Delete is a soft delete - records can be restored within 90 days
  • •Delete endpoints return HTTP 204 (No Content) on success
  • •The industry property on companies requires specific enum values
  • •IMPORTANT: When using curl commands, use curl -g when URLs contain brackets (fields[], sort[], records[]) to disable glob parsing
  • •IMPORTANT: When piping curl output to jq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments. You may get "Invalid API key" errors when piping.

Error Handling

StatusMeaning
400Missing HubSpot connection
401Invalid or missing Maton API key
429Rate limited (10 req/sec per account)
4xx/5xxPassthrough error from HubSpot API

Troubleshooting: Invalid API Key

When you receive a "Invalid API key" error, ALWAYS follow these steps before concluding there is an issue:

  1. •Check that the MATON_API_KEY environment variable is set:
bash
echo $MATON_API_KEY
  1. •Verify the API key is valid by listing connections:
bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Resources