Try Live
Add Docs
Rankings
Pricing
Docs
Install
Theme
Install
Docs
Pricing
More...
More...
Try Live
Rankings
Enterprise
Create API Key
Add Docs
HubSpot Public APIs
https://github.com/hubspot/hubspot-public-api-spec-collection
Admin
HubSpot Public APIs is a repository of OpenAPI 3.0 schemas for HubSpot's public APIs, integrated
...
Tokens:
22,904
Snippets:
90
Trust Score:
8.5
Update:
1 month ago
Context
Skills
Chat
Benchmark
78.9
Suggestions
Latest
Show doc for...
Code
Info
Show Results
Context Summary (auto-generated)
Raw
Copy
Link
# HubSpot Public APIs HubSpot Public APIs provide a comprehensive suite of RESTful endpoints for integrating with HubSpot's marketing, sales, and customer service platform. The APIs follow OpenAPI 3.0 specifications and enable developers to programmatically manage CRM objects (contacts, companies, deals, tickets), automate marketing workflows, handle file management, configure webhooks, and access account information. All APIs use `https://api.hubapi.com` as the base URL and support OAuth 2.0 and private app authentication. The API collection covers the full HubSpot ecosystem including CRM management (contacts, companies, deals, tickets, pipelines, properties, associations), marketing automation (campaigns, forms, emails, events), content management (files, folders), account administration (account info, audit logs, API usage), and developer tools (webhooks, OAuth). Each API supports standard CRUD operations with batch processing capabilities, advanced search with filtering, and pagination for large datasets. ## Authentication ### OAuth 2.0 Authorization OAuth 2.0 is the primary authentication method for HubSpot integrations, allowing apps to access HubSpot data on behalf of users with granular scope permissions. ```bash # Step 1: Redirect users to authorize your app # Authorization URL: https://app.hubspot.com/oauth/authorize curl "https://app.hubspot.com/oauth/authorize?\ client_id=YOUR_CLIENT_ID&\ redirect_uri=https://your-app.com/callback&\ scope=crm.objects.contacts.read%20crm.objects.contacts.write&\ state=random_state_string" # Step 2: Exchange authorization code for access token curl -X POST https://api.hubapi.com/oauth/v1/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=authorization_code&\ client_id=YOUR_CLIENT_ID&\ client_secret=YOUR_CLIENT_SECRET&\ redirect_uri=https://your-app.com/callback&\ code=AUTHORIZATION_CODE" # Response: # { # "access_token": "CLjK0qzKLxIDAQEY...", # "refresh_token": "d29b732f-0fd8-...", # "expires_in": 1800, # "token_type": "bearer" # } # Step 3: Use access token in API requests curl https://api.hubapi.com/crm/v3/objects/contacts \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" # Step 4: Refresh access token when expired curl -X POST https://api.hubapi.com/oauth/v1/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=refresh_token&\ client_id=YOUR_CLIENT_ID&\ client_secret=YOUR_CLIENT_SECRET&\ refresh_token=YOUR_REFRESH_TOKEN" ``` ### Private App Authentication Private apps provide API key-based authentication for server-to-server integrations without user interaction. ```bash # Use private app access token in Authorization header curl https://api.hubapi.com/crm/v3/objects/contacts \ -H "Authorization: Bearer YOUR_PRIVATE_APP_ACCESS_TOKEN" # Or use the private-app header curl https://api.hubapi.com/crm/v3/objects/contacts \ -H "private-app: YOUR_PRIVATE_APP_ACCESS_TOKEN" ``` ## Account Information API ### Get Account Details Retrieve account details such as the account type, time zone, currencies, and data hosting location. ```bash curl https://api.hubapi.com/account-info/v3/details \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" # Response: # { # "portalId": 12345678, # "accountType": "STANDARD", # "timeZone": "US/Eastern", # "companyCurrency": "USD", # "additionalCurrencies": ["NZD", "AUD", "EUR"], # "utcOffset": "-04:00", # "utcOffsetMilliseconds": -14400000, # "uiDomain": "app.hubspot.com", # "dataHostingLocation": "na1" # } ``` ### Get API Usage Retrieve the daily API usage for private apps in the account, along with information about usage limits. ```bash curl https://api.hubapi.com/account-info/v3/api-usage/daily/private-apps \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" # Response: # { # "results": [{ # "name": "private-apps-api-calls-daily", # "usageLimit": 500000, # "currentUsage": 1523, # "collectedAt": "2024-01-15T06:46:40.789Z", # "fetchStatus": "SUCCESS", # "resetsAt": "2024-01-16T04:00:00Z" # }] # } ``` ### Get Audit Logs Retrieve activity history for user actions related to approvals, content updates, CRM object updates, and security activity (Enterprise only). ```bash curl "https://api.hubapi.com/account-info/v3/activity/audit-logs?\ occurredAfter=2024-01-01T00:00:00Z&\ occurredBefore=2024-01-31T23:59:59Z&\ limit=100" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" # Response: # { # "results": [{ # "id": "abc123", # "actingUserId": 12345, # "action": "UPDATED", # "objectType": "CONTACT", # "objectId": "501", # "occurredAt": "2024-01-15T14:30:00Z" # }], # "paging": { # "next": { # "after": "eyJsYXN0..." # } # } # } ``` ### Get Login Activity Retrieve logs of user actions related to login activity. ```bash curl "https://api.hubapi.com/account-info/v3/activity/login?\ userId=12345&\ limit=50" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` ## Contacts API ### List Contacts Read a page of contacts with optional property filtering and pagination. ```bash curl "https://api.hubapi.com/crm/v3/objects/contacts?\ limit=10&\ properties=firstname,lastname,email,phone&\ archived=false" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" # Response: # { # "results": [{ # "id": "501", # "properties": { # "firstname": "John", # "lastname": "Doe", # "email": "john.doe@example.com", # "phone": "+1-555-0100", # "createdate": "2024-01-10T08:30:00.000Z", # "lastmodifieddate": "2024-01-15T14:22:00.000Z" # }, # "createdAt": "2024-01-10T08:30:00.000Z", # "updatedAt": "2024-01-15T14:22:00.000Z", # "archived": false # }], # "paging": { # "next": { # "after": "NTI1Cg%3D%3D", # "link": "?after=NTI1Cg%3D%3D" # } # } # } ``` ### Get Contact by ID Read a single contact by ID or unique property value. ```bash # Get by internal ID curl "https://api.hubapi.com/crm/v3/objects/contacts/501?\ properties=firstname,lastname,email,phone,company" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" # Get by email (unique property) curl "https://api.hubapi.com/crm/v3/objects/contacts/john.doe@example.com?\ idProperty=email&\ properties=firstname,lastname,phone" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" # Get with associations curl "https://api.hubapi.com/crm/v3/objects/contacts/501?\ associations=companies,deals&\ properties=firstname,lastname,email" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` ### Create Contact Create a new contact with properties and optional associations. ```bash curl -X POST https://api.hubapi.com/crm/v3/objects/contacts \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "properties": { "email": "jane.smith@example.com", "firstname": "Jane", "lastname": "Smith", "phone": "+1-555-0101", "company": "Acme Corp", "website": "https://acme.com", "lifecyclestage": "lead" }, "associations": [{ "to": {"id": "123"}, "types": [{ "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 1 }] }] }' # Response: # { # "id": "502", # "properties": { # "email": "jane.smith@example.com", # "firstname": "Jane", # "lastname": "Smith", # "phone": "+1-555-0101", # "company": "Acme Corp", # "createdate": "2024-01-15T16:00:00.000Z", # "lastmodifieddate": "2024-01-15T16:00:00.000Z" # }, # "createdAt": "2024-01-15T16:00:00.000Z", # "updatedAt": "2024-01-15T16:00:00.000Z", # "archived": false # } ``` ### Update Contact Perform a partial update of a contact by ID. ```bash curl -X PATCH https://api.hubapi.com/crm/v3/objects/contacts/501 \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "properties": { "phone": "+1-555-0199", "lifecyclestage": "customer", "hs_lead_status": "CONNECTED" } }' # Update by email (unique property) curl -X PATCH "https://api.hubapi.com/crm/v3/objects/contacts/john.doe@example.com?\ idProperty=email" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "properties": { "phone": "+1-555-0199" } }' ``` ### Archive Contact Move a contact to the recycling bin. ```bash curl -X DELETE https://api.hubapi.com/crm/v3/objects/contacts/501 \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" # Response: 204 No Content ``` ### Search Contacts Search for contacts using filters and criteria. ```bash curl -X POST https://api.hubapi.com/crm/v3/objects/contacts/search \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "filterGroups": [{ "filters": [{ "propertyName": "email", "operator": "CONTAINS_TOKEN", "value": "example.com" }, { "propertyName": "lifecyclestage", "operator": "EQ", "value": "lead" }] }], "sorts": ["createdate"], "properties": ["firstname", "lastname", "email", "company"], "limit": 20, "after": "0" }' # Response: # { # "total": 45, # "results": [{ # "id": "503", # "properties": { # "firstname": "Alice", # "lastname": "Johnson", # "email": "alice@example.com", # "company": "Tech Inc" # } # }], # "paging": { # "next": {"after": "20"} # } # } # Search with multiple filter groups (OR logic between groups) curl -X POST https://api.hubapi.com/crm/v3/objects/contacts/search \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "filterGroups": [ { "filters": [{ "propertyName": "lifecyclestage", "operator": "EQ", "value": "customer" }] }, { "filters": [{ "propertyName": "hs_lead_status", "operator": "EQ", "value": "QUALIFIED" }] } ], "properties": ["firstname", "lastname", "email"], "limit": 50 }' ``` ### Batch Create Contacts Create multiple contacts in a single request. ```bash curl -X POST https://api.hubapi.com/crm/v3/objects/contacts/batch/create \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "inputs": [ { "properties": { "email": "contact1@example.com", "firstname": "Contact", "lastname": "One" }, "associations": [] }, { "properties": { "email": "contact2@example.com", "firstname": "Contact", "lastname": "Two" }, "associations": [] } ] }' # Response: # { # "status": "COMPLETE", # "results": [{ # "id": "504", # "properties": {...} # }, { # "id": "505", # "properties": {...} # }], # "startedAt": "2024-01-15T16:30:00.000Z", # "completedAt": "2024-01-15T16:30:01.000Z" # } ``` ### Batch Read Contacts Retrieve multiple contacts by ID or unique property values. ```bash curl -X POST https://api.hubapi.com/crm/v3/objects/contacts/batch/read \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "properties": ["firstname", "lastname", "email", "phone"], "propertiesWithHistory": [], "inputs": [ {"id": "501"}, {"id": "502"}, {"id": "503"} ] }' # Read by email addresses curl -X POST https://api.hubapi.com/crm/v3/objects/contacts/batch/read \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "properties": ["firstname", "lastname"], "propertiesWithHistory": [], "idProperty": "email", "inputs": [ {"id": "john@example.com"}, {"id": "jane@example.com"} ] }' ``` ### Batch Update Contacts Update multiple contacts using their internal IDs or unique property values. ```bash curl -X POST https://api.hubapi.com/crm/v3/objects/contacts/batch/update \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "inputs": [ { "id": "501", "properties": { "lifecyclestage": "customer" } }, { "id": "502", "properties": { "lifecyclestage": "opportunity" } } ] }' ``` ### Batch Upsert Contacts Create or update contacts identified by a unique property value. ```bash curl -X POST https://api.hubapi.com/crm/v3/objects/contacts/batch/upsert \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "inputs": [ { "id": "new.contact@example.com", "idProperty": "email", "properties": { "email": "new.contact@example.com", "firstname": "New", "lastname": "Contact" } }, { "id": "existing@example.com", "idProperty": "email", "properties": { "phone": "+1-555-9999" } } ] }' # Response includes whether each record was created or updated: # { # "results": [{ # "id": "506", # "new": true, # "properties": {...} # }, { # "id": "501", # "new": false, # "properties": {...} # }] # } ``` ### Merge Contacts Combine two contacts into a single contact record. ```bash curl -X POST https://api.hubapi.com/crm/v3/objects/contacts/merge \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "primaryObjectId": "501", "objectIdToMerge": "502" }' # The contact 502 will be merged into 501 # Response returns the merged contact record ``` ## Companies API ### List Companies Read a page of companies with optional property filtering. ```bash curl "https://api.hubapi.com/crm/v3/objects/companies?\ limit=10&\ properties=name,domain,industry,numberofemployees" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" # Response: # { # "results": [{ # "id": "101", # "properties": { # "name": "Acme Corporation", # "domain": "acme.com", # "industry": "TECHNOLOGY", # "numberofemployees": "500" # } # }] # } ``` ### Create Company Create a new company record with properties. ```bash curl -X POST https://api.hubapi.com/crm/v3/objects/companies \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "properties": { "name": "TechStart Inc", "domain": "techstart.io", "industry": "TECHNOLOGY", "description": "An innovative tech startup", "numberofemployees": "50", "annualrevenue": "5000000", "city": "San Francisco", "state": "California", "country": "United States" }, "associations": [] }' ``` ### Update Company Update company properties by ID. ```bash curl -X PATCH https://api.hubapi.com/crm/v3/objects/companies/101 \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "properties": { "numberofemployees": "750", "annualrevenue": "25000000", "lifecyclestage": "customer" } }' ``` ### Search Companies Search for companies with filters. ```bash curl -X POST https://api.hubapi.com/crm/v3/objects/companies/search \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "filterGroups": [{ "filters": [{ "propertyName": "industry", "operator": "EQ", "value": "TECHNOLOGY" }, { "propertyName": "numberofemployees", "operator": "GTE", "value": "100" }] }], "properties": ["name", "domain", "industry", "numberofemployees"], "limit": 25 }' ``` ## Deals API ### List Deals Read a page of deals to track transactions with contacts and companies. ```bash curl "https://api.hubapi.com/crm/v3/objects/deals?\ limit=10&\ properties=dealname,amount,closedate,pipeline,dealstage&\ associations=contacts,companies" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" # Response: # { # "results": [{ # "id": "201", # "properties": { # "dealname": "Enterprise License - Acme Corp", # "amount": "50000", # "closedate": "2024-03-31", # "pipeline": "default", # "dealstage": "contractsent" # }, # "associations": { # "contacts": { # "results": [{"id": "501", "type": "deal_to_contact"}] # }, # "companies": { # "results": [{"id": "101", "type": "deal_to_company"}] # } # } # }] # } ``` ### Create Deal Create a new deal with properties and associations. ```bash curl -X POST https://api.hubapi.com/crm/v3/objects/deals \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "properties": { "dealname": "New Software License", "amount": "75000", "closedate": "2024-06-30", "pipeline": "default", "dealstage": "appointmentscheduled", "hubspot_owner_id": "12345" }, "associations": [ { "to": {"id": "501"}, "types": [{ "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 3 }] }, { "to": {"id": "101"}, "types": [{ "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 5 }] } ] }' ``` ### Update Deal Stage Update a deal's stage as it progresses through the pipeline. ```bash curl -X PATCH https://api.hubapi.com/crm/v3/objects/deals/201 \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "properties": { "dealstage": "closedwon", "amount": "55000", "closedate": "2024-01-20" } }' ``` ### Search Deals Search for deals with complex filtering. ```bash curl -X POST https://api.hubapi.com/crm/v3/objects/deals/search \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "filterGroups": [{ "filters": [ { "propertyName": "amount", "operator": "GTE", "value": "10000" }, { "propertyName": "dealstage", "operator": "IN", "values": ["qualifiedtobuy", "presentationscheduled", "decisionmakerboughtin"] }, { "propertyName": "closedate", "operator": "BETWEEN", "value": "2024-01-01", "highValue": "2024-03-31" } ] }], "sorts": ["-amount"], "properties": ["dealname", "amount", "closedate", "dealstage"], "limit": 50 }' ``` ### Batch Create Deals Create multiple deals in a single request. ```bash curl -X POST https://api.hubapi.com/crm/v3/objects/deals/batch/create \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "inputs": [ { "properties": { "dealname": "Deal A", "amount": "25000", "pipeline": "default", "dealstage": "appointmentscheduled" }, "associations": [] }, { "properties": { "dealname": "Deal B", "amount": "50000", "pipeline": "default", "dealstage": "qualifiedtobuy" }, "associations": [] } ] }' ``` ## Tickets API ### List Tickets Read support tickets with their properties. ```bash curl "https://api.hubapi.com/crm/v3/objects/tickets?\ limit=10&\ properties=subject,content,hs_pipeline,hs_pipeline_stage,hs_ticket_priority" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" # Response: # { # "results": [{ # "id": "301", # "properties": { # "subject": "Unable to login", # "content": "Customer reports login issues...", # "hs_pipeline": "0", # "hs_pipeline_stage": "1", # "hs_ticket_priority": "HIGH" # } # }] # } ``` ### Create Ticket Create a new support ticket. ```bash curl -X POST https://api.hubapi.com/crm/v3/objects/tickets \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "properties": { "subject": "Product inquiry", "content": "Customer wants to know about enterprise features", "hs_pipeline": "0", "hs_pipeline_stage": "1", "hs_ticket_priority": "MEDIUM", "hs_ticket_category": "PRODUCT_ISSUE" }, "associations": [ { "to": {"id": "501"}, "types": [{ "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 16 }] } ] }' ``` ## Pipelines API ### List Pipelines Retrieve all pipelines for a specific object type (deals or tickets). ```bash # Get all deal pipelines curl https://api.hubapi.com/crm/v3/pipelines/deals \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" # Get all ticket pipelines curl https://api.hubapi.com/crm/v3/pipelines/tickets \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" # Response: # { # "results": [{ # "id": "default", # "label": "Sales Pipeline", # "displayOrder": 0, # "stages": [ # {"id": "appointmentscheduled", "label": "Appointment Scheduled", "displayOrder": 0}, # {"id": "qualifiedtobuy", "label": "Qualified To Buy", "displayOrder": 1}, # {"id": "presentationscheduled", "label": "Presentation Scheduled", "displayOrder": 2}, # {"id": "closedwon", "label": "Closed Won", "displayOrder": 3}, # {"id": "closedlost", "label": "Closed Lost", "displayOrder": 4} # ] # }] # } ``` ### Get Pipeline by ID Retrieve a specific pipeline with its stages. ```bash curl https://api.hubapi.com/crm/v3/pipelines/deals/default \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` ### Create Pipeline Create a new pipeline with custom stages. ```bash curl -X POST https://api.hubapi.com/crm/v3/pipelines/deals \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "label": "Enterprise Sales Pipeline", "displayOrder": 1, "stages": [ {"label": "Discovery", "displayOrder": 0, "metadata": {"probability": "0.1"}}, {"label": "Proposal", "displayOrder": 1, "metadata": {"probability": "0.4"}}, {"label": "Negotiation", "displayOrder": 2, "metadata": {"probability": "0.7"}}, {"label": "Closed Won", "displayOrder": 3, "metadata": {"probability": "1.0"}}, {"label": "Closed Lost", "displayOrder": 4, "metadata": {"probability": "0"}} ] }' ``` ## Properties API ### List Properties Read all existing properties for a specified object type. ```bash curl "https://api.hubapi.com/crm/v3/properties/contacts?\ archived=false" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" # Response: # { # "results": [ # { # "name": "email", # "label": "Email", # "type": "string", # "fieldType": "text", # "groupName": "contactinformation", # "calculated": false, # "hasUniqueValue": true # }, # { # "name": "firstname", # "label": "First Name", # "type": "string", # "fieldType": "text", # "groupName": "contactinformation" # } # ] # } ``` ### Create Property Create a custom property for an object type. ```bash curl -X POST https://api.hubapi.com/crm/v3/properties/contacts \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "favorite_color", "label": "Favorite Color", "type": "enumeration", "fieldType": "select", "groupName": "contactinformation", "description": "Customer preferred color", "options": [ {"label": "Red", "value": "red", "displayOrder": 0}, {"label": "Blue", "value": "blue", "displayOrder": 1}, {"label": "Green", "value": "green", "displayOrder": 2} ] }' # Create a multi-select property curl -X POST https://api.hubapi.com/crm/v3/properties/companies \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "contract_terms", "label": "Contract Terms", "type": "enumeration", "fieldType": "checkbox", "groupName": "companyinformation", "options": [ {"label": "Annual Billing", "value": "annual", "displayOrder": 0}, {"label": "Monthly Billing", "value": "monthly", "displayOrder": 1}, {"label": "Net 30", "value": "net30", "displayOrder": 2} ] }' ``` ### Update Property Update an existing property definition. ```bash curl -X PATCH https://api.hubapi.com/crm/v3/properties/contacts/favorite_color \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "label": "Preferred Color", "options": [ {"label": "Red", "value": "red", "displayOrder": 0}, {"label": "Blue", "value": "blue", "displayOrder": 1}, {"label": "Green", "value": "green", "displayOrder": 2}, {"label": "Yellow", "value": "yellow", "displayOrder": 3} ] }' ``` ## Associations API (v4) ### Create Associations Associate two CRM objects together. ```bash # Associate a contact with a company curl -X POST https://api.hubapi.com/crm/v4/associations/contacts/companies/batch/create \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "inputs": [ { "from": {"id": "501"}, "to": {"id": "101"}, "types": [ { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 1 } ] } ] }' # Associate a deal with multiple contacts curl -X POST https://api.hubapi.com/crm/v4/associations/deals/contacts/batch/create \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "inputs": [ { "from": {"id": "201"}, "to": {"id": "501"}, "types": [{"associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 3}] }, { "from": {"id": "201"}, "to": {"id": "502"}, "types": [{"associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 3}] } ] }' ``` ### Delete Associations Remove associations between objects. ```bash curl -X POST https://api.hubapi.com/crm/v4/associations/contacts/companies/batch/archive \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "inputs": [ { "from": {"id": "501"}, "to": [{"id": "101"}] } ] }' ``` ## Files API ### Upload File Upload a single file to the HubSpot file manager. ```bash curl -X POST https://api.hubapi.com/files/v3/files \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -F "file=@/path/to/document.pdf" \ -F "fileName=contract-2024.pdf" \ -F "folderPath=/contracts/2024" \ -F 'options={"access": "PUBLIC_INDEXABLE", "ttl": "P3M"}' # Response: # { # "id": "12345678901", # "name": "contract-2024.pdf", # "path": "/contracts/2024/contract-2024.pdf", # "url": "https://app.hubspot.com/file-preview/...", # "size": 125000, # "type": "application/pdf", # "access": "PUBLIC_INDEXABLE" # } ``` ### Import File from URL Asynchronously import a file from a URL into the file manager. ```bash curl -X POST https://api.hubapi.com/files/v3/files/import-from-url/async \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/images/logo.png", "name": "company-logo.png", "folderPath": "/assets/images", "access": "PUBLIC_INDEXABLE", "duplicateValidationStrategy": "NONE" }' # Response: # { # "id": "task-12345", # "status": "PENDING" # } # Check import status curl https://api.hubapi.com/files/v3/files/import-from-url/async/tasks/task-12345/status \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` ### Search Files Search for files in the file manager. ```bash curl -X POST https://api.hubapi.com/files/v3/files/search \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "filterGroups": [{ "filters": [{ "propertyName": "type", "operator": "EQ", "value": "IMG" }] }], "sorts": ["-updatedAt"], "limit": 20 }' ``` ### Get File by ID Retrieve file metadata and download URL. ```bash curl https://api.hubapi.com/files/v3/files/12345678901 \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` ### Delete File Permanently delete a file or move it to trash. ```bash curl -X DELETE https://api.hubapi.com/files/v3/files/12345678901 \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` ## Webhooks API ### Get Webhook Settings Retrieve the webhook settings for your app. ```bash curl https://api.hubapi.com/webhooks/v3/YOUR_APP_ID/settings \ -H "Authorization: Bearer YOUR_DEVELOPER_API_KEY" # Response: # { # "targetUrl": "https://www.example.com/hubspot/webhook", # "throttling": { # "period": "SECONDLY", # "maxConcurrentRequests": 10 # }, # "createdAt": "2024-01-01T10:00:00Z", # "updatedAt": "2024-01-15T14:30:00Z" # } ``` ### Configure Webhook Settings Update webhook settings for your app. ```bash curl -X PUT https://api.hubapi.com/webhooks/v3/YOUR_APP_ID/settings \ -H "Authorization: Bearer YOUR_DEVELOPER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "targetUrl": "https://www.example.com/hubspot/events", "throttling": { "period": "SECONDLY", "maxConcurrentRequests": 10 } }' ``` ### Create Subscription Subscribe to specific events. ```bash curl -X POST https://api.hubapi.com/webhooks/v3/YOUR_APP_ID/subscriptions \ -H "Authorization: Bearer YOUR_DEVELOPER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "eventType": "contact.creation", "active": true }' # Subscribe to deal stage changes curl -X POST https://api.hubapi.com/webhooks/v3/YOUR_APP_ID/subscriptions \ -H "Authorization: Bearer YOUR_DEVELOPER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "eventType": "deal.propertyChange", "propertyName": "dealstage", "active": true }' # Subscribe to contact deletions curl -X POST https://api.hubapi.com/webhooks/v3/YOUR_APP_ID/subscriptions \ -H "Authorization: Bearer YOUR_DEVELOPER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "eventType": "contact.deletion", "active": true }' ``` ### List Subscriptions Get all event subscriptions for your app. ```bash curl https://api.hubapi.com/webhooks/v3/YOUR_APP_ID/subscriptions \ -H "Authorization: Bearer YOUR_DEVELOPER_API_KEY" # Response: # { # "results": [ # { # "id": "123456", # "eventType": "contact.creation", # "active": true, # "createdAt": "2024-01-01T10:00:00Z" # }, # { # "id": "123457", # "eventType": "deal.propertyChange", # "propertyName": "dealstage", # "active": true, # "createdAt": "2024-01-02T11:00:00Z" # } # ] # } ``` ### Delete Webhook Settings Delete webhook settings (subscriptions will be paused). ```bash curl -X DELETE https://api.hubapi.com/webhooks/v3/YOUR_APP_ID/settings \ -H "Authorization: Bearer YOUR_DEVELOPER_API_KEY" ``` ## Search Filter Operators The search API supports the following filter operators for building complex queries: ```bash # EQ - Equal to {"propertyName": "lifecyclestage", "operator": "EQ", "value": "customer"} # NEQ - Not equal to {"propertyName": "industry", "operator": "NEQ", "value": "TECHNOLOGY"} # LT - Less than {"propertyName": "amount", "operator": "LT", "value": "10000"} # LTE - Less than or equal to {"propertyName": "createdate", "operator": "LTE", "value": "2024-01-31"} # GT - Greater than {"propertyName": "numberofemployees", "operator": "GT", "value": "100"} # GTE - Greater than or equal to {"propertyName": "annualrevenue", "operator": "GTE", "value": "1000000"} # BETWEEN - Between two values (inclusive) {"propertyName": "closedate", "operator": "BETWEEN", "value": "2024-01-01", "highValue": "2024-12-31"} # IN - Value is one of the specified values {"propertyName": "dealstage", "operator": "IN", "values": ["closedwon", "closedlost"]} # NOT_IN - Value is not one of the specified values {"propertyName": "lifecyclestage", "operator": "NOT_IN", "values": ["subscriber", "lead"]} # CONTAINS_TOKEN - Contains the specified token (for text search) {"propertyName": "email", "operator": "CONTAINS_TOKEN", "value": "example.com"} # NOT_CONTAINS_TOKEN - Does not contain the specified token {"propertyName": "email", "operator": "NOT_CONTAINS_TOKEN", "value": "spam"} # HAS_PROPERTY - Property has any value (not null) {"propertyName": "phone", "operator": "HAS_PROPERTY"} # NOT_HAS_PROPERTY - Property has no value (is null) {"propertyName": "hs_lead_status", "operator": "NOT_HAS_PROPERTY"} ``` ## Error Handling All HubSpot APIs return standardized error responses with correlation IDs for troubleshooting. ```bash # Example error response: # { # "status": "error", # "message": "Invalid input (details will vary based on the error)", # "correlationId": "aeb5f871-7f07-4993-9211-075dc63e7cbf", # "category": "VALIDATION_ERROR", # "errors": [ # { # "message": "Property values were not valid: [{\"isValid\":false,\"message\":\"Email is invalid\",\"error\":\"INVALID_EMAIL\",\"name\":\"email\"}]", # "context": { # "propertyName": ["email"] # } # } # ], # "links": { # "knowledge-base": "https://www.hubspot.com/products/service/knowledge-base" # } # } # Common HTTP status codes: # 200 - Success # 201 - Created # 204 - No Content (successful deletion) # 400 - Bad Request (validation error) # 401 - Unauthorized (invalid or expired token) # 403 - Forbidden (insufficient scopes) # 404 - Not Found # 429 - Too Many Requests (rate limited) # 500 - Internal Server Error ``` ## Summary The HubSpot Public APIs enable comprehensive integration with HubSpot's marketing, sales, and service platforms. Primary use cases include syncing CRM data between HubSpot and external systems, automating contact and deal management workflows, building custom reporting dashboards, triggering actions based on CRM events via webhooks, and managing files and assets programmatically. The APIs support batch operations for efficient bulk data processing, advanced search capabilities with multiple filter operators, and real-time event notifications through webhooks. Integration patterns typically involve OAuth 2.0 authentication for user-authorized access or private apps for server-to-server communication. Developers should implement proper error handling with retry logic for rate-limited requests (429 responses), use batch endpoints when processing multiple records to minimize API calls, leverage webhook subscriptions for event-driven architectures, and cache frequently accessed data like pipelines and properties to optimize performance. All APIs are available on the FREE tier with appropriate scopes, making them accessible for integrations of any scale.