hubspot – OpenClaw Skill

---

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. 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

# Create a contact
curl -s -X POST 'https://gateway.maton.ai/hubspot/crm/v3/objects/contacts' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "properties": {
      "email": "john@example.com",
      "firstname": "John",
      "lastname": "Doe"
    }
  }'

Base URL

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:

Authorization: Bearer YOUR_API_KEY

Environment Variable: Set your API key as MATON_API_KEY:

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

curl -s -X GET 'https://ctrl.maton.ai/connections?app=hubspot&status=ACTIVE' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Create Connection

curl -s -X POST 'https://ctrl.maton.ai/connections' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{"app": "hubspot"}'

Get Connection

curl -s -X GET 'https://ctrl.maton.ai/connections/{connection_id}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response:

{
  "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

curl -s -X DELETE 'https://ctrl.maton.ai/connections/{connection_id}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Specifying Connection

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

curl -s -X GET 'https://gateway.maton.ai/hubspot/crm/v3/objects/contacts' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Maton-Connection: 21fd90f9-5935-43cd-b6c8-bde9d915ca80'

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

API Reference

Contacts

List Contacts

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

With pagination:

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

Get Contact

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

Create Contact

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

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

Update Contact

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

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

Delete Contact

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

Search Contacts

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

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

Get Company

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

Create Company

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

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

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

Delete Company

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

Search Companies

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

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

Get Deal

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

Create Deal

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

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

Update Deal

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

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

Delete Deal

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

Associations (v4 API)

Associate Objects

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

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

Batch Operations

Batch Read

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

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

Batch Create

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

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

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

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

Properties

List Properties

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:

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

Use the after query parameter to fetch the next page:

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

Code Examples

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

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

Error Handling

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

Resources

• HubSpot API Overview
• List Contacts
• Create Contact
• Search Contacts
• List Companies
• Create Company
• List Deals
• Create Deal
• Associations API
• Properties API
• Search Reference