hubspot

# 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 ``` 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`: ```bash export MATON_API_KEY="YOUR_API_KEY" ``` ### Getting Your API Key 1. Sign in or create an account at [maton.ai](https://maton.ai) 2. Go to [maton.ai/settings](https://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"}] } ```