HubSpot

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

Instalar
$clawhub install hubspot-api

HubSpot

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

Quick Start

# 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

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 $MATON_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

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

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

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

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:

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

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": "[email protected]",
    "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": "[email protected]"
    }]
  }],
  "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": "[email protected]", "firstname": "One"}},
    {"properties": {"email": "[email protected]", "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: '[email protected]', 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': '[email protected]', '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

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

Troubleshooting: API Key Issues

  1. Check that the MATON_API_KEY environment variable is set:
echo $MATON_API_KEY
  1. Verify the API key is valid by listing connections:
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

Troubleshooting: Invalid App Name

  1. Ensure your URL path starts with hubspot. For example:
  • Correct: https://gateway.maton.ai/hubspot/crm/v3/objects/contacts
  • Incorrect: https://gateway.maton.ai/crm/v3/objects/contacts

Resources

Detalhes

Versão
v1.0.4
Downloads
3,677
Estrelas
4
ClawHub
Ver no ClawHub

Skills populares

Firecrawl Search
Web search and scraping via Firecrawl API. Use when you need to search the web, scrape websites (including JS-heavy pages), crawl entire sites, or extract structured data from web pages. Requires FIRECRAWL_API_KEY environment variable.
Ai Act Risk Check
Assesses AI system risk polarity based on Annex III of the EU AI Act, identifying high-risk categories like biometrics and employment.
Github
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.