HubSpot Public APIs (hubspot/hubspot-public-api-spec-collection)

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
Show doc for...
Context Summary (auto-generated)
Raw
# 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.