cotera
Logo

HubSpot

Authentication Type: Private App Access Token Description: Customer relationship management platform for managing deals, contacts, companies, and sales pipelines.

Authentication

Cotera authenticates to HubSpot with a private app access token, which HubSpot sends as a bearer token on each request. HubSpot's legacy API keys were sunset in 2022 and replaced by private app access tokens, so you'll create a private app to generate a token:

  1. Go to Settings > Integrations > Private Apps in your HubSpot account
  2. Click Create a private app
  3. Give your app a name and description
  4. 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
  5. Click Create app
  6. Copy the access token from the Access token section

For more details, see the HubSpot private app access token documentation. HubSpot also offers OAuth 2.0 for public apps that connect to multiple accounts, but Cotera's HubSpot tool uses a single-account private app access token.

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", "IN", "NOT_IN")
    • value string (nullable): Value to filter by; use values instead for IN and NOT_IN
    • values array of strings (nullable): Multiple values for IN and NOT_IN operators
    • 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.

Create Contact

Create a new contact with specified properties and optional associations to companies or deals.

Operation Type: Mutation (Write)

Parameters:

  • properties array of objects (required): Array of key-value pairs for contact properties
    • key string (required): Property name (e.g., "email", "firstname", "lastname", "company")
    • 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., "contact_to_company")

Returns:

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

Example Usage:

{
  "properties": [
    { "key": "email", "value": "jane.smith@acme.com" },
    { "key": "firstname", "value": "Jane" },
    { "key": "lastname", "value": "Smith" },
    { "key": "company", "value": "Acme Corp" },
    { "key": "jobtitle", "value": "VP of Engineering" }
  ],
  "associations": [
    {
      "to": "987654321",
      "type": "contact_to_company"
    }
  ]
}

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 (nullable): Value to filter by; use values instead for IN and NOT_IN
    • values array of strings (nullable): Multiple values for IN and NOT_IN operators
    • 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"]
}

HubSpot Email Bounce Status

Check whether one or more email addresses have bounced in the past by looking up their HubSpot contacts. Returns a per-email bounce flag (hard or soft), hard bounce status, reason, and marketing bounce count.

Operation Type: Query (Read)

Parameters:

  • emails array of strings (required): Email addresses to check. Each is looked up against the HubSpot contact email property.
  • additionalProperties array of strings (optional, default: null): Extra contact properties to fetch and include in each result's properties map (e.g. hs_email_optout, hs_email_quarantined). The bounce-signal properties are always fetched.

Returns:

  • results array of objects: One entry per input email, in input order
    • email string: The input email address
    • found boolean: Whether a HubSpot contact with this email was found
    • contactId string | null: Matched contact ID, or null if not found
    • hasBounced boolean: True if this email has bounced (hard or soft) — either a hard bounce reason is set or marketingEmailsBounced is greater than 0
    • hasHardBounced boolean: True if this email has specifically hard bounced — a permanent, undeliverable failure
    • hardBounceReason string | null: The last hard bounce reason (hs_email_hard_bounce_reason, falling back to the enum code hs_email_hard_bounce_reason_enum, e.g. UNKNOWN_USER), or null
    • marketingEmailsBounced number: Count of marketing emails that hard or soft bounced for this contact (hs_email_bounce)
    • properties object: Matched contact properties (bounce-signal fields always included; additional properties if requested)
  • bouncedCount number: Number of input rows that have bounced — counts per row, not per unique contact
  • uniqueBouncedContactCount number: Number of distinct HubSpot contacts (by contact ID) that have bounced — deduplicates repeated lookups of the same contact
  • notFoundCount number: Number of input rows with no matching HubSpot contact

Behavior Notes:

  • Lookup lowercases and deduplicates email addresses for the HubSpot IN search, but returns one result row per original input email in input order.
  • hasBounced is true when either a hard bounce reason exists (hasHardBounced) or marketingEmailsBounced is greater than 0.
  • hardBounceReason uses hs_email_hard_bounce_reason (free-text), falling back to hs_email_hard_bounce_reason_enum (e.g. UNKNOWN_USER) when the free-text value is empty.
  • marketingEmailsBounced reflects HubSpot's marketing email bounce count (hs_email_bounce), not global bounces or one-to-one sales sends.
  • bouncedCount counts input rows, while uniqueBouncedContactCount deduplicates by HubSpot contact ID.

Example Usage:

{
  "emails": ["alice@example.com", "bob@example.com", "ALICE@EXAMPLE.COM"],
  "additionalProperties": ["hs_email_optout", "hs_email_quarantined"]
}

Companies

Manage company records in your HubSpot CRM.

Create Company

Create a new company with specified properties and optional associations to contacts or deals.

Operation Type: Mutation (Write)

Parameters:

  • properties array of objects (required): Array of key-value pairs for company properties
    • key string (required): Property name (e.g., "name", "domain", "industry", "annualrevenue", "numberofemployees", "city", "state", "country", "phone")
    • 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): The HubSpot-defined association type ID

Returns:

  • id string: Created company ID
  • properties object: Company properties
  • createdAt string: Creation timestamp
  • updatedAt string: Last update timestamp
  • archived boolean: Whether the company is archived

Example Usage:

{
  "properties": [
    { "key": "name", "value": "Acme Corporation" },
    { "key": "domain", "value": "acme.com" },
    { "key": "industry", "value": "TECHNOLOGY" },
    { "key": "numberofemployees", "value": "500" },
    { "key": "city", "value": "San Francisco" },
    { "key": "state", "value": "CA" }
  ]
}

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"
}

Sequences

Enroll contacts in HubSpot sales sequences and check enrollment status. All sequence tools use the HubSpot Automation Sequences API (v2026-03).

List Sequences

Retrieve a paginated list of all HubSpot sales sequences available in your account.

Operation Type: Query (Read)

Parameters:

  • userId string (required): The HubSpot user ID whose sequences to list
  • limit number (nullable): Maximum results to return (max: 100)

Returns:

  • total number (nullable): Total number of sequences
  • results array of objects: Array of sequence records
    • id string: Sequence ID
    • name string: Sequence name
    • createdAt string: Creation timestamp
    • updatedAt string: Last update timestamp
    • userId string: Owner user ID
    • folderId string: Folder ID the sequence belongs to
  • paging object (nullable): Pagination info
    • next object (nullable): Next page cursor
    • limit number: Page size used

Example Usage:

{
  "userId": "12345",
  "limit": 50
}

Get Contact Sequence Enrollment

Check whether a HubSpot contact is currently enrolled in a sales sequence.

Operation Type: Query (Read)

Behavior Notes:

  • A 404 response from HubSpot (contact not enrolled in any sequence) is mapped to enrolled: false rather than throwing an error, so callers can always branch on the enrolled field without handling exceptions.

Parameters:

  • contactId string (required): The unique identifier of the HubSpot contact to check

Returns:

  • enrolled boolean: Whether the contact is currently enrolled in a sequence
  • enrollment object (nullable): Present when enrolled is true
    • id string: Enrollment ID
    • toEmail string: Email address the sequence is sending to
    • enrolledAt string: Enrollment timestamp
    • updatedAt string: Last update timestamp
    • sequenceId string: ID of the sequence the contact is enrolled in
    • sequenceName string: Name of the sequence
    • enrolledBy string: User ID of the person who enrolled the contact
    • enrolledByEmail string: Email of the person who enrolled the contact

Example Usage:

{
  "contactId": "12345678"
}

Enroll Contact in Sequence

Enroll a HubSpot contact into a sales sequence. This operation is idempotent — if the contact is already enrolled in the specified sequence, no duplicate enrollment is created.

Operation Type: Mutation (Write)

Behavior Notes:

  • The tool checks current enrollment before creating a new one to prevent duplicates. If the contact is already enrolled in the target sequence, the existing enrollment is returned.
  • Uses strict input validation on enrollment parameters via the HubSpot Automation Sequences API (v2026-03).

Parameters:

  • userId string (required): The HubSpot user ID performing the enrollment
  • sequenceId string (required): The ID of the sequence to enroll the contact into
  • contactId string (required): The unique identifier of the contact to enroll
  • senderEmail string (required): The email address the sequence emails will be sent from
  • senderAliasAddress string (nullable): An optional alias address to send from instead of senderEmail

Returns:

  • id string: Enrollment ID
  • toEmail string: Email address the sequence is sending to
  • enrolledAt string: Enrollment timestamp
  • updatedAt string: Last update timestamp

Example Usage:

{
  "userId": "12345",
  "sequenceId": "67890",
  "contactId": "11111111",
  "senderEmail": "rep@company.com"
}

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