HubSpot

Authentication Type: API Key Description: Customer relationship management platform for managing deals, contacts, companies, and sales pipelines.

Authentication

To authenticate, you'll need to create a HubSpot private app:

Go to Settings > Integrations > Private Apps in your HubSpot account
Click Create a private app
Give your app a name and description
Go to the Scopes tab and select the permissions your app needs:
- crm.objects.contacts.read - Read contacts
- crm.objects.contacts.write - Update contacts
- crm.objects.deals.read - Read deals
- crm.objects.deals.write - Create/update deals
- crm.objects.companies.read - Read companies
- sales-email-read - Read email engagements
Click Create app
Copy the access token from the Access token section

For more details, see the HubSpot Private Apps documentation.

Deals

Manage sales deals and opportunities in your HubSpot CRM pipeline.

Search Deals

Search for deals using filters based on property values. Supports date ranges, status filtering, and pagination.

Operation Type: Query (Read)

Parameters:

filters array of objects (nullable): Array of filter criteria
- propertyName string (required): The property to filter on
- operator string (required): Filter operator (e.g., "EQ", "GTE", "LTE", "CONTAINS")
- value string (required): Value to filter by
- highValue string (nullable): Upper bound for BETWEEN operator
sorts array of objects (nullable): Array of sort criteria
- propertyName string (required): Property to sort by
- direction string (required): Sort direction ("ASCENDING" or "DESCENDING")
properties array of strings (nullable): Specific properties to return
limit number (nullable): Maximum results to return (default: 10, max: 100)
after string (nullable): Pagination cursor for next page

Returns:

total number: Total number of matching deals
results array of objects: Array of deal records
- id string: Deal ID
- properties object: Deal properties (key-value pairs)
- createdAt string: Creation timestamp
- updatedAt string: Last update timestamp
- archived boolean: Whether the deal is archived
paging object (nullable): Pagination info
- next object (nullable): Next page cursor

Example Usage:

{
  "filters": [
    {
      "propertyName": "dealstage",
      "operator": "EQ",
      "value": "closedwon"
    }
  ],
  "sorts": [
    {
      "propertyName": "closedate",
      "direction": "DESCENDING"
    }
  ],
  "properties": ["dealname", "amount", "closedate", "dealstage"],
  "limit": 25
}

Get Deal

Retrieve a specific deal by its ID, including selected properties and optionally associated records.

Operation Type: Query (Read)

Parameters:

dealId string (required): The unique identifier for the deal
properties array of strings (nullable): Specific properties to return
associations array of strings (nullable): Associated objects to include (e.g., "contacts", "companies")

Returns:

id string: Deal ID
properties object: Deal properties (key-value pairs)
createdAt string: Creation timestamp
updatedAt string: Last update timestamp
archived boolean: Whether the deal is archived

Example Usage:

{
  "dealId": "12345678",
  "properties": ["dealname", "amount", "closedate", "dealstage", "pipeline"],
  "associations": ["contacts", "companies"]
}

Create Deal

Create a new deal with specified properties and optional associations to contacts or companies.

Operation Type: Mutation (Write)

Parameters:

properties array of objects (required): Array of key-value pairs for deal properties
- key string (required): Property name (e.g., "dealname", "amount", "dealstage")
- value string (required): Property value
associations array of objects (nullable): Optional associations to create
- to string (required): ID of the record to associate
- type string (required): Association type (e.g., "deal_to_contact")

Returns:

id string: Created deal ID
properties object: Deal properties
createdAt string: Creation timestamp
updatedAt string: Last update timestamp
archived boolean: Whether the deal is archived

Example Usage:

{
  "properties": [
    { "key": "dealname", "value": "Enterprise License Agreement" },
    { "key": "amount", "value": "50000" },
    { "key": "dealstage", "value": "presentationscheduled" },
    { "key": "pipeline", "value": "default" }
  ],
  "associations": [
    {
      "to": "123456",
      "type": "deal_to_contact"
    }
  ]
}

Update Deal

Update properties on an existing deal.

Operation Type: Mutation (Write)

Parameters:

dealId string (required): The unique identifier for the deal
properties array of objects (required): Array of key-value pairs to update
- key string (required): Property name
- value string (required): New property value

Returns:

id string: Deal ID
properties object: Updated deal properties
createdAt string: Creation timestamp
updatedAt string: Last update timestamp
archived boolean: Whether the deal is archived

Example Usage:

{
  "dealId": "12345678",
  "properties": [
    { "key": "dealstage", "value": "closedwon" },
    { "key": "amount", "value": "75000" }
  ]
}

List Deals

Retrieve a paginated list of all deals with optional property selection.

Operation Type: Query (Read)

Parameters:

limit number (nullable): Maximum results to return (default: 10, max: 100)
after string (nullable): Pagination cursor
properties array of strings (nullable): Specific properties to return

Returns:

results array of objects: Array of deal records
paging object (nullable): Pagination info

Example Usage:

{
  "limit": 50,
  "properties": ["dealname", "amount", "dealstage", "closedate"]
}

Contacts

Manage individual contacts and their information in HubSpot CRM.

Search Contacts

Search for contacts using filters based on property values like email, name, or custom properties.

Operation Type: Query (Read)

Parameters:

filters array of objects (nullable): Array of filter criteria
- propertyName string (required): The property to filter on
- operator string (required): Filter operator
- value string (required): Value to filter by
- highValue string (nullable): Upper bound for BETWEEN operator
sorts array of objects (nullable): Array of sort criteria
properties array of strings (nullable): Specific properties to return
limit number (nullable): Maximum results to return
after string (nullable): Pagination cursor

Returns:

total number: Total number of matching contacts
results array of objects: Array of contact records
paging object (nullable): Pagination info

Example Usage:

{
  "filters": [
    {
      "propertyName": "email",
      "operator": "CONTAINS_TOKEN",
      "value": "@acme.com"
    }
  ],
  "properties": ["email", "firstname", "lastname", "company", "jobtitle"],
  "limit": 25
}

Get Contact

Retrieve a specific contact by their ID, including selected properties and optionally associated records.

Operation Type: Query (Read)

Parameters:

contactId string (required): The unique identifier for the contact
properties array of strings (nullable): Specific properties to return
associations array of strings (nullable): Associated objects to include

Returns:

id string: Contact ID
properties object: Contact properties
createdAt string: Creation timestamp
updatedAt string: Last update timestamp
archived boolean: Whether the contact is archived

Example Usage:

{
  "contactId": "12345678",
  "properties": ["email", "firstname", "lastname", "phone", "company", "jobtitle"],
  "associations": ["deals", "companies"]
}

List Contacts

Retrieve a paginated list of all contacts with optional property selection.

Operation Type: Query (Read)

Parameters:

limit number (nullable): Maximum results to return
after string (nullable): Pagination cursor
properties array of strings (nullable): Specific properties to return

Returns:

results array of objects: Array of contact records
paging object (nullable): Pagination info

Example Usage:

{
  "limit": 50,
  "properties": ["email", "firstname", "lastname", "company"]
}

Update Contact

Update properties on an existing contact.

Operation Type: Mutation (Write)

Parameters:

contactId string (required): The unique identifier for the contact
properties array of objects (required): Array of key-value pairs to update
- key string (required): Property name
- value string (required): New property value

Returns:

id string: Contact ID
properties object: Updated contact properties
createdAt string: Creation timestamp
updatedAt string: Last update timestamp
archived boolean: Whether the contact is archived

Example Usage:

{
  "contactId": "12345678",
  "properties": [
    { "key": "jobtitle", "value": "VP of Sales" },
    { "key": "phone", "value": "+1-555-123-4567" }
  ]
}

Get Communications

Retrieve all communications (emails, notes, calls, meetings, tasks) associated with a contact, sorted by timestamp.

Operation Type: Query (Read)

Parameters:

contactId string (required): The unique identifier for the contact
types array of strings (nullable): Communication types to fetch (email, note, call, meeting, task). Fetches all types if not specified.

Returns:

results array of objects: Array of communications sorted by timestamp (most recent first)
- id string: Communication ID
- type string: Type of communication (email, note, call, meeting, task)
- properties object: Communication properties
- timestamp string: Communication timestamp
- createdAt string: Creation timestamp
- updatedAt string: Last update timestamp

Example Usage:

{
  "contactId": "12345678",
  "types": ["email", "note"]
}

Notes

Create and manage notes attached to deals, contacts, and other CRM records.

List Notes

Retrieve a paginated list of all notes with optional property selection.

Operation Type: Query (Read)

Parameters:

limit number (nullable): Maximum results to return
after string (nullable): Pagination cursor
properties array of strings (nullable): Specific properties to return

Returns:

results array of objects: Array of note records
paging object (nullable): Pagination info

Example Usage:

{
  "limit": 25,
  "properties": ["hs_note_body", "hs_timestamp"]
}

Get Note

Retrieve a specific note by its ID.

Operation Type: Query (Read)

Parameters:

noteId string (required): The unique identifier for the note
properties array of strings (nullable): Specific properties to return

Returns:

id string: Note ID
properties object: Note properties including body and timestamp
createdAt string: Creation timestamp
updatedAt string: Last update timestamp
archived boolean: Whether the note is archived

Example Usage:

{
  "noteId": "12345678",
  "properties": ["hs_note_body", "hs_timestamp", "hubspot_owner_id"]
}

Create Note

Create a new note with content and optionally associate it with deals, contacts, or other CRM records.

Operation Type: Mutation (Write)

Parameters:

body string (required): The content of the note (max 65536 chars)
timestamp string (nullable): Unix timestamp in milliseconds or UTC format. Defaults to current time.
ownerId string (nullable): The ID of the HubSpot owner to associate with this note
associations array of objects (nullable): Optional associations to create
- to string (required): ID of the record to associate
- type string (required): Association type (e.g., "note_to_contact", "note_to_deal")

Returns:

id string: Created note ID
properties object: Note properties
createdAt string: Creation timestamp
updatedAt string: Last update timestamp
archived boolean: Whether the note is archived

Example Usage:

{
  "body": "Had a productive call with the customer. They're interested in upgrading to the enterprise plan. Follow up scheduled for next week.",
  "associations": [
    {
      "to": "12345678",
      "type": "note_to_contact"
    },
    {
      "to": "87654321",
      "type": "note_to_deal"
    }
  ]
}

Update Note

Update an existing note's body, timestamp, or owner.

Operation Type: Mutation (Write)

Parameters:

noteId string (required): The unique identifier for the note
body string (nullable): Updated note content
timestamp string (nullable): Updated timestamp
ownerId string (nullable): Updated owner ID

Returns:

id string: Note ID
properties object: Updated note properties
createdAt string: Creation timestamp
updatedAt string: Last update timestamp
archived boolean: Whether the note is archived

Example Usage:

{
  "noteId": "12345678",
  "body": "Updated: Customer confirmed they want to proceed with the enterprise plan. Contract sent for review."
}

Emails

Access email engagements logged in HubSpot CRM.

Get Email

Retrieve a specific email engagement by its ID, including subject, body, direction, and timestamp.

Operation Type: Query (Read)

Parameters:

emailId string (required): The unique identifier for the email
properties array of strings (nullable): Specific properties to return

Returns:

id string: Email ID
properties object: Email properties including subject, body, direction
createdAt string: Creation timestamp
updatedAt string: Last update timestamp
archived boolean: Whether the email is archived

Example Usage:

{
  "emailId": "12345678",
  "properties": ["hs_email_subject", "hs_email_text", "hs_email_direction", "hs_timestamp"]
}

Pipelines

View sales pipeline configurations and stages for organizing deal progression.

List Pipelines

Retrieve all pipelines for a given object type (deals or tickets), including their stages and configuration.

Operation Type: Query (Read)

Parameters:

objectType string (required): The object type (deals or tickets)

Returns:

results array of objects: Array of pipeline objects
- id string: Pipeline ID
- label string: Pipeline display name
- displayOrder number: Display order
- stages array of objects: Pipeline stages
- createdAt string: Creation timestamp
- updatedAt string: Last update timestamp
- archived boolean: Whether the pipeline is archived

Example Usage:

{
  "objectType": "deals"
}

Get Pipeline Stages

Retrieve all stages within a specific pipeline, including stage probabilities and order.

Operation Type: Query (Read)

Parameters:

objectType string (required): The object type (deals or tickets)
pipelineId string (required): The pipeline ID

Returns:

results array of objects: Array of pipeline stage objects
- id string: Stage ID
- label string: Stage display name
- displayOrder number: Display order
- metadata object: Stage metadata including probability
- createdAt string: Creation timestamp
- updatedAt string: Last update timestamp
- archived boolean: Whether the stage is archived

Example Usage:

{
  "objectType": "deals",
  "pipelineId": "default"
}

Associations

Retrieve relationships between CRM records like deals-to-contacts or notes-to-deals.

List Associations

Get all records of a specific type associated with a given record.

Operation Type: Query (Read)

Parameters:

fromObjectType string (required): The source object type (e.g., "contacts", "deals")
objectId string (required): The ID of the source object
toObjectType string (required): The target object type to find associations to

Returns:

results array of objects: Array of association objects
- toObjectId string: ID of the associated object
- associationTypes array of objects: Types of associations
  - category string: Association category (HUBSPOT_DEFINED or USER_DEFINED)
  - typeId number: Association type ID
  - label string (nullable): Association label

Example Usage:

{
  "fromObjectType": "deals",
  "objectId": "12345678",
  "toObjectType": "contacts"
}

Common Use Cases

Deal Management:

Search deals by stage, amount, or close date to track pipeline health
Create deals with associations to contacts and companies for complete context
Update deal stages as opportunities progress through the sales cycle

Contact Intelligence:

Search contacts by company or job title to find decision makers
Get all communications history for a contact before meetings
Update contact information when roles or details change

Activity Tracking:

Create notes to log meeting outcomes and action items
Retrieve email history to understand engagement patterns
Track all touchpoints across deals and contacts

Pipeline Analytics:

List pipeline stages to understand your sales process
Get deals by stage to measure conversion rates
Track deal progression through pipeline stages over time