Hubspot

1. Overview

HubSpot is a comprehensive CRM platform that provides software and support to help businesses grow. It includes tools for marketing, sales, customer service, and content management, all powered by a single, connected database.

The GoInsight Hubspot node allows you to seamlessly integrate your CRM data and operations into your automated workflows. You can manage the entire lifecycle of key CRM objects, including:

• Companies: Create, update, retrieve, and delete company records.
• Contacts: Create, update, find, and delete contacts, and manage their inclusion in lists.
• Deals: Manage your sales pipeline by creating, updating, searching for, and deleting deals.
• Tickets: Handle customer support by creating, updating, retrieving, and deleting service tickets.
• Engagements: Log activities like notes, calls, emails, and meetings associated with your CRM records.

2. Prerequisites

Before using this node, you need to have a valid Hubspot account. You may also need administrative permissions or specific user roles within your HubSpot account to create and manage API credentials required for authentication.

3. Credentials

For a detailed guide on how to obtain and configure your credentials, please refer to our official documentation: Credentials Configuration Guide.

4. Supported Operations

Summary

This node primarily operates on resources such as Company, Contact, Deal, Ticket, Engagement, List, and Pipeline.

Operation Details

Create a Company

Create a new company record in HubSpot CRM. Core: CompanyName (required), CompanyDomain (strongly recommended). Duplicate protection enabled by default via CheckDuplicateByDomain - checks if a company with the same domain exists before creating. May trigger HubSpot workflows if automation rules are configured.

Input Parameters:

• CompanyName: Company name (required). Example: 'Acme Corporation'

Options:

• CompanyDomain: Company domain name (e.g., 'acme.com'). HubSpot uses this to automatically link contacts whose email matches this domain. Also used for duplicate checking when CheckDuplicateByDomain is enabled. Strongly recommended.
• Website: Full website URL with protocol. Different from CompanyDomain. Example: 'https://www.acme.com'
• Industry: Industry type. Auto-converted to HubSpot format (uppercased, underscores). Common: ACCOUNTING (Accounting/Finance), COMPUTER_SOFTWARE (Software), MARKETING_ADVERTISING (Marketing/Ads), INFORMATION_TECHNOLOGY_AND_SERVICES (IT Services), FINANCIAL_SERVICES (Finance), RETAIL (Retail). Full list: see HubSpot docs. Example: 'COMPUTER_SOFTWARE'
• Phone: Phone number with country code. Example: '+1-415-555-0100'
• City: City where the company is located. Example: 'San Francisco'
• Country: Country. Use English full name or ISO code (e.g., 'United States' or 'US')
• CheckDuplicateByDomain: Check for existing company by domain before creating (default: true). If true and a matching company exists, returns error instead of creating duplicate. Recommended to keep enabled.
• AdditionalFields: Extra company properties as key-value pairs. Common: state (State/Province), description (company description), zip (postal code), numberofemployees, annualrevenue. Example: {"state": "California", "description": "Leading provider of enterprise software solutions"}

Output:

• CompanyId (string): Newly created company's unique ID (numeric string). Use this ID in Update a Company, Delete Company, or Get a Company actions. Example: '12345678901'
• PortalId (string): HubSpot portal ID (numeric string). Example: '987654321'
• CompanyProperties (object): Created company properties object. Core fields (all strings): name, domain, website, industry, phone, city, country. Additional fields (if provided): state, description, zip, numberofemployees, annualrevenue, etc. System fields: createdate (ISO 8601), hs_lastmodifieddate, hs_object_id (same as CompanyId).
• OriginalStatusCode (number): Original HTTP status code from HubSpot API. 0=request didn't reach upstream, 201=Created, 401=Auth failed, 429=Rate limited
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System/network error
• ErrorMessage (string): Detailed error message if failed, empty string on success

Delete Company

Permanently deletes one or more HubSpot companies. WARNING: This operation CANNOT be undone. Deleted companies cannot be recovered. Deleting a company does NOT delete associated contacts or deals; those records remain but lose company association. When deleting multiple IDs, each one is processed separately, so partial success is possible. If StatusCode=200 and ErrorMessage is not empty, check FailedItems for details. Failure example: AllDeleted=false, FailedItems includes {companyId, statusCode, errorMessage}, ErrorMessage may be 'Partial success: X deleted, Y failed'.

Input Parameters:

• CompanyId: A single HubSpot company ID or comma-separated list of IDs to delete. Spaces around commas are automatically trimmed (e.g. '12345, 67890'). Obtain IDs from Search Companies, Find Company, or Get Recent Companies

Output:

• AllDeleted (bool): True if all companies were deleted successfully. False if ANY deletion failed (including partial failures). For per-ID failure details, check FailedItems
• FailedItems (object-array): Array of failed deletion objects (object-array). Each object contains: companyId (string), statusCode (number), errorMessage (string). Example: [{"companyId": "67890", "statusCode": 404, "errorMessage": "API Error (404): Company not found"}]
• OriginalStatusCode (number): Upstream HTTP status summary. In batch mode: 204 means all deleted successfully; 0 means request did not reach upstream; otherwise this is the first failed request status code (for example 404 not found, 429 rate limited). Use FailedItems for per-ID details
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for partial failures), -1=Parameter error, 500=System/network error
• ErrorMessage (string): Error details if failed, empty on full success

Get Companies

Retrieve multiple HubSpot companies by company IDs using batch API. Returns company objects with requested properties.

Input Parameters:

• CompanyIds: Comma-separated company IDs to retrieve. Supports large inputs by automatically splitting into HubSpot batch chunks of up to 100 IDs per upstream request. Obtain from Create a Company -> CompanyId, Search Companies, or Get Recent Companies -> Companies[].id. Example: 12345678901,12345678902

Options:

• Properties: Comma-separated list of company property names to return. Spaces around commas are allowed and trimmed automatically. Common: name, domain, industry, city, state, country, phone, website, numberofemployees, annualrevenue. Leave empty for default 8 fields

Output:

• Companies (object-array): Array of company objects. Each contains: id (string), properties (object with requested fields), createdAt (ISO 8601 timestamp), updatedAt (ISO 8601 timestamp), archived (boolean)
• Hint (string): Actionable recovery suggestion when ErrorMessage is non-empty. Empty on success.
• Retryable (bool): Whether the error is transient and safe to retry immediately. Usually true for StatusCode=500 or OriginalStatusCode=429; otherwise false.
• Summary (string): One-line execution summary for quick context and downstream chaining.
• OriginalStatusCode (number): Upstream HTTP status code (diagnostic-only; do not use it to infer success/failure). 0 means no upstream HTTP response was received (e.g., timeout/network error).
• StatusCode (number): Tool-level status code. 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Primary success/failure signal. Empty string means SUCCESS; non-empty means FAILURE (contains reason and ideally a recovery hint).

Get Recent Companies

Retrieve recently created or updated HubSpot companies with pagination support.

Options:

• UpdatedAfterTimestamp: UNIX timestamp (seconds) to filter companies updated after this time. If empty, retrieves from the last 24 hours. How to convert: Python: int(datetime(2024,1,1).timestamp()), JavaScript: Math.floor(new Date('2024-01-01').getTime()/1000), or use online converter. Example: 1704067200 (2024-01-01 00:00:00 UTC)
• Limit: Maximum number of companies to retrieve (1-100). Default: 50
• Properties: Comma-separated company property names to return. Spaces around commas are automatically removed. Common properties: name, domain, industry, city/state/country, phone, website, description, annualrevenue, numberofemployees, lifecyclestage. Default: name,domain,industry,city,state,country,phone,website,description. Example: 'name,domain,industry,annualrevenue,lifecyclestage'
• SortDirection: Sort by last modified date: DESCENDING (default, newest first) or ASCENDING (oldest first, useful for incremental sync)
• UseSearchEndpoint: ⚠️ Advanced option: use the advanced search interface (recommended) or the simpler objects listing interface. Search endpoint ('true', recommended): supports stronger filtering, better performance for large datasets, and consistent sorting. Basic objects endpoint ('false'): simpler API, faster for small queries, limited to a single date filter. Default: 'true'. Most users should keep the default.
• PagingAfter: Pagination cursor from previous response. Leave empty for first page. Use value from previous response's PagingAfter field to get next page. Example: '12346'

Output:

• Companies (object-array): Array of company objects. Each contains: id (string, HubSpot company ID), properties (object, DYNAMIC fields based on Properties input parameter - only requested fields are returned. All values are STRINGS, even for numeric-looking fields such as annualrevenue and numberofemployees. Example: {"name": "Acme Corp", "annualrevenue": "1000000", "numberofemployees": "50", "lifecyclestage": "customer"}), createdAt (string, ISO 8601), updatedAt (string, ISO 8601), archived (boolean, whether company is archived)
• TotalCount (number): Number of companies returned in this page
• HasMore (bool): true if more pages available. Use PagingAfter input parameter with this response's PagingAfter value to get next page
• PagingAfter (string): Cursor for next page. Pass this value to PagingAfter input parameter to fetch next page. Empty string if no more pages
• OriginalStatusCode (number): Original HTTP status code from HubSpot API. 0=didn't reach upstream, 200=Success, 400=Bad request, 429=Rate limited
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter error, 500=System/network error
• ErrorMessage (string): Error details if failed, empty on success

Get a Company

Retrieves detailed information for a HubSpot company using its company ID.

Input Parameters:

• CompanyId: Unique ID of the HubSpot company to retrieve (required). Obtain from Create a Company, Find Company, or Get Recent Companies actions. Example: '12345678901'

Options:

• IncludeMergeAudits: Whether to include company merge history. In plain language: if two company records were merged in HubSpot, this returns which older company record was merged into the current one and when. Useful for data cleanup, duplicate-resolution review, and audit scenarios. Default: true

Output:

• PortalId (string): HubSpot portal ID
• CompanyId (string): HubSpot company ID
• CompanyName (string): Name of the company (from properties.name)
• CompanyDomain (string): Company's primary domain name (from properties.domain)
• IsDeleted (bool): true if the company is soft-deleted: hidden from normal views but not permanently erased, so HubSpot admins may still be able to restore it. false means the company is in normal active state.
• Properties (object): JSON object of company property values in HubSpot v2 format. Structure: each key is a property name, and each property value is an object such as {"value": "Acme Corp", "timestamp": 1234567890, "source": "CRM_UI"}. Common keys include name, domain, industry, phone, city, country, website, description, annual_revenue, and num_employees. The value field is typically a string even for numeric-looking properties.
• AdditionalDomains (object-array): Array of additional domain objects beyond the primary domain. Each element is an object such as {"domain": "brand.example", "isPrimary": false}. Empty if none.
• StateChanges (object-array): Array of state change records that track lifecycle events such as MERGED or RESTORED. Each element is an object containing fields like state (string), timestamp (number, milliseconds), and portalId (number or string). Empty if none.
• MergeAudits (object-array): Array of merge audit records (only if IncludeMergeAudits=true). Each element is an object describing a merge event, typically including mergedFromCompanyId (string or number), mergeTimestamp (number, milliseconds), and related audit metadata. Use this to understand which older company record was merged into the current one and when. Empty if no merges.
• OriginalStatusCode (number): Original HTTP status code from HubSpot API. 0=didn't reach upstream, 200=Success, 404=Not found, 429=Rate limited
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter error, 500=System/network error
• ErrorMessage (string): Error details if failed, empty on success

Find Company

Search HubSpot companies by domain and return matching company objects.

Input Parameters:

• Domain: Company domain to search for. URLs with protocol/path are auto-cleaned (e.g. 'https://airdroid.com/features' → 'airdroid.com'). Example: 'airdroid.com'

Options:

• Limit: The maximum number of companies to return, must be between 1 and 100 (default 10).
• ExactMatch: Domain matching mode. True (default) = exact match (only exact domain). False = contains match (e.g. 'airdroid' returns 'airdroid.com', 'airdroid.cn'). Use True for known domains, False for brand name search.
• After: Pagination cursor. Leave empty for first page. Use the NextAfter value from the previous response to get the next page.

Output:

• Results (object-array): Array of company objects. Each contains: Id (string): HubSpot company unique ID; Name (string): company name; Domain (string): company website domain; Industry (string): industry category (HubSpot enum, e.g. 'COMPUTER_SOFTWARE', 'RETAIL'); CreateDate (string): creation timestamp in ISO 8601 UTC format; LastModifiedDate (string): last update timestamp in ISO 8601 UTC format. Empty array if no matches.
• Pagination (object): Pagination metadata object. Contains: ReturnedCount (number): companies in this response; RequestedLimit (number): the limit value from request; TotalCount (number): total matching companies in HubSpot; HasMore (boolean): true if more results exist beyond this page. When HasMore is true, use NextAfter as the After input to get the next page.
• NextAfter (string): Pagination cursor for the next page. Empty string if no more pages exist. Pass this value as the After input on the next call.
• OriginalStatusCode (number): Original HTTP status code from HubSpot API. 0=didn't reach upstream, 200=Success, 400=Bad request, 429=Rate limited
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter error, 500=System/network error
• ErrorMessage (string): Error details if failed, empty on success

Update a Company

Update a HubSpot company record by company ID. Update strategy: only the properties you specify will be changed — all other fields remain unchanged (PATCH). You don't need to provide all company info, just the fields you want to update. Example: if you only set phone, the company's name, domain, and other fields stay the same.

Input Parameters:

• CompanyId: Company ID to update (required). Format: numeric string (e.g. '12345678901', not a number). Obtain from Create a Company → CompanyId, Search Companies, or Get Recent Companies → Companies[].id. Example: '12345678901'
• Properties: ⚠️ ALL values must be strings, even numbers (e.g. '50000' not 50000). Object of company properties to update. Only specified fields are changed (PATCH). Common: name, domain, website, industry, city, state, country, phone, description, numberofemployees, annualrevenue. ⚠️ The industry field requires HubSpot ALL_CAPS enum values — human-readable strings cause a 400 error. Common industry values: COMPUTER_SOFTWARE, INTERNET_TECHNOLOGY, TECHNOLOGY, FINANCIAL_SERVICES, BANKING, RETAIL, CONSUMER_GOODS, HEALTHCARE, HOSPITAL_HEALTH_CARE, EDUCATION_MANAGEMENT, MARKETING_AND_ADVERTISING, REAL_ESTATE, MANUFACTURING, TRANSPORTATION_TRUCKING_RAILROAD, OTHER. For the full list, call Get Company Properties or see HubSpot CRM Properties documentation.

Output:

• UpdatedCompany (object): Full company object after update. Contains: id (string, company ID), properties (object with ALL company fields including unchanged ones — common keys: name, domain, industry, phone, city, state, country, website, numberofemployees, annualrevenue, createdate, hs_lastmodifieddate), createdAt (string ISO 8601), updatedAt (string ISO 8601), archived (boolean). Note: HubSpot returns the complete record, not just updated fields.
• OriginalStatusCode (number): Original HTTP status code from HubSpot API. 0=didn't reach upstream, 200=Updated, 404=Not found, 429=Rate limited
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter error, 500=System/network error
• ErrorMessage (string): Error details if failed, empty on success

Create or Update Contact

Creates or updates a HubSpot contact record using email as the primary identifier with comprehensive field validation.

Input Parameters:

• Email: Contact email (required). Primary identifier for upsert: existing contact is updated, otherwise a new one is created. Example: 'john.doe@acme.com'

Options:

• FirstName: Contact first name. Example: 'John'
• LastName: Contact last name. Example: 'Doe'
• Company: Company name associated with the contact. Example: 'Acme Corporation'
• Phone: Phone number with country code. Example: '+1-415-555-0100'
• Website: Website URL with protocol. Example: 'https://www.johndoe.com'
• LifecycleStage: Lifecycle stage (forward-only in HubSpot). Order: subscriber -> lead -> marketingqualifiedlead (MQL) -> salesqualifiedlead (SQL) -> opportunity -> customer -> evangelist -> other. You cannot move backward (e.g., customer -> lead). Example: 'lead'

Output:

• ContactId (string): Unique ID of the created/updated contact (numeric string). Use in Get a Contact, Delete Contact actions. Example: '12345678'
• IsNewContact (bool): true if a new contact was created, false if an existing contact was updated
• Hint (string): Actionable recovery suggestion when ErrorMessage is non-empty. Empty on success.
• Retryable (bool): Whether the error is transient and safe to retry immediately. Usually true for StatusCode=500 or OriginalStatusCode=429; otherwise false.
• Summary (string): One-line execution summary for quick context and downstream chaining.
• OriginalStatusCode (number): Upstream HTTP status code (diagnostic-only; do not use it to infer success/failure). 0 means no upstream HTTP response was received (e.g., timeout/network error).
• StatusCode (number): Tool-level status code. 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Primary success/failure signal. Empty string means SUCCESS; non-empty means FAILURE (contains reason and ideally a recovery hint).

Delete Contact

Permanently deletes one or more HubSpot contacts. WARNING: This operation CANNOT be undone. Deleted contacts cannot be recovered.

Input Parameters:

• ContactId: A single HubSpot contact ID or comma-separated list of IDs to delete. Obtain from Search Contacts or Get Contacts (id field). Example: '12345' or '12345,67890'

Output:

• AllDeleted (bool): true if all contacts were deleted, false if any failed
• FailedItems (object-array): Array of failed deletion objects. Each contains: contactId (string), statusCode (number, e.g. 404=Not found), errorMessage (string). Empty if all succeeded
• OriginalStatusCode (number): Last HTTP status code from HubSpot API. 0=Network timeout or connection failed, 204=Deleted, 404=Not found, 429=Rate limited
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for partial failures), -1=Parameter error, 500=System/network error
• ErrorMessage (string): Error details if failed, empty on full success

Get Contacts

Retrieve multiple HubSpot contacts with pagination support and flexible property selection. HubSpot limits pagination to 10,000 total results. Use Search Contacts with filters for larger datasets.

Options:

• Limit: Maximum number of contacts to return per page (default 10, max 100)
• After: Pagination cursor for next page. Use the NextCursor value from previous response. Leave empty for first page. Example: '12346'
• Properties: Comma-separated contact property names (data fields) to return. Common: email, firstname, lastname, company, phone, website, industry, jobtitle, lifecyclestage. Default: email,firstname,lastname,company,phone
• Archived: 'false' (default) = active contacts only, 'true' = archived (soft-deleted) contacts only
• PropertiesWithHistory: Comma-separated properties to include historical change values with timestamps. Leave empty to skip. Example: 'email,phone'

Output:

• Contacts (object-array): Array of contact objects. Each contains: Id (string), Properties (object - fields depend on Properties input, all values are strings), PropertiesWithHistory (object - each property has array of {value, timestamp, sourceType}), CreatedAt (ISO 8601), UpdatedAt (ISO 8601), Archived (boolean)
• Total (number): Number of contacts returned in current page
• HasMore (bool): true if more pages available. Use NextCursor value in After parameter to get next page
• NextCursor (string): Pagination cursor for next page. Pass as After input parameter. Empty if no more pages
• OriginalStatusCode (number): Original HTTP status code from HubSpot API. 0=didn't reach upstream, 200=Success, 400=Bad request, 429=Rate limited
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter error, 500=System/network error
• ErrorMessage (string): Error details if failed, empty on success

Get Recent Contacts

Retrieve recently created or updated HubSpot contacts with precise date filtering, timezone support, and comprehensive

synchronization capabilities for incremental data processing workflows.

Input Parameters:

• StartDate: Start date (required). ISO 8601 format with timezone. Examples: UTC '2024-01-01T00:00:00Z', Beijing time '2024-01-01T00:00:00+08:00'. Date only '2024-01-01' treated as UTC midnight.

Options:

• ModificationType: Filter type (case-insensitive). Valid values: 'created' (only new contacts in date range, for acquisition tracking), 'updated' (only modified contacts excluding new ones, for activity monitoring), 'both' (contacts created OR updated, for full data sync). Default: 'updated'
• EndDate: End date (optional). ISO 8601 format with timezone. Must be after StartDate. Examples: UTC '2024-01-31T23:59:59Z', Beijing time '2024-01-31T23:59:59+08:00'
• Limit: Max contacts per page (1-100). Default: 100
• After: Pagination cursor from previous response's NextCursor field. Empty for first page. This is an opaque string generated by HubSpot - do NOT manually construct. Cursors expire after 24 hours. Example: 'NTI1Cg%3D%3D'
• Properties: Comma-separated contact property names to return. Spaces around commas are allowed and trimmed automatically. Common: email, firstname, lastname, company, phone, createdate, lastmodifieddate, jobtitle, lifecyclestage (lead/opportunity/customer), website, industry, hs_lead_status, address, city, state, zip. For full list, refer to HubSpot documentation. Default: email,firstname,lastname,company,phone,createdate,lastmodifieddate
• SortDirection: Sort order. Valid values: DESCENDING (default, newest first) or ASCENDING (oldest first, useful for incremental sync). Case-insensitive.

Output:

• Contacts (object-array): Array of contact objects. Each contains: Id (string, HubSpot contact ID), Properties (object keyed by requested property names; common keys include email, firstname, lastname, company, phone, createdate, lastmodifieddate), CreatedAt (string, ISO 8601), UpdatedAt (string, ISO 8601), Archived (boolean)
• Total (number): Number of contacts returned in this page
• HasMore (bool): true if more results available. Use NextCursor value as After input parameter to get next page
• NextCursor (string): Pagination cursor for next page. Pass as After input parameter in next call. Empty string if no more pages
• Hint (string): Actionable recovery suggestion when ErrorMessage is non-empty. Empty on success.
• Retryable (bool): Whether the error is transient and safe to retry immediately. Usually true for StatusCode=500 or OriginalStatusCode=429; otherwise false.
• Summary (string): One-line execution summary for quick context and downstream chaining.
• OriginalStatusCode (number): Upstream HTTP status code (diagnostic-only; do not use it to infer success/failure). 0 means no upstream HTTP response was received (e.g., timeout/network error).
• StatusCode (number): Tool-level status code. 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Primary success/failure signal. Empty string means SUCCESS; non-empty means FAILURE (contains reason and ideally a recovery hint).

Get a Contact

Retrieves a HubSpot contact identified by either its contact ID or email address, specifying which properties to return via a comma-separated string.

Input Parameters:

• ContactIdentifier: HubSpot contact ID or email address (required). Auto-detects email by '@'. To get Contact ID, use Search Contacts or List Contacts actions. Example: '12345678' or 'john@acme.com'

Options:

• Properties: Comma-separated contact field names to return. Common: firstname, lastname, email, phone, company (basic); createdate, lastmodifieddate (timestamps); hs_object_id (ID). Defaults to all above. Example: 'firstname,email,phone'

Output:

• Contact (object): JSON object of the contact. Contains: id (string), properties (object with requested fields, all string values), createdAt (ISO 8601), updatedAt (ISO 8601), archived (boolean). Empty {} if not found - check ErrorMessage first.
• OriginalStatusCode (number): Original HTTP status code from HubSpot API. 0=didn't reach upstream, 200=Success, 404=Not found, 429=Rate limited
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter error, 500=System/network error
• ErrorMessage (string): Error details if failed, empty on success

Search Contacts

Search HubSpot contacts by email address or general query with flexible matching and comprehensive error handling. Supports pagination for large result sets.

Input Parameters:

• Query: Search query with intelligent matching: email format (e.g., john@acme.com) performs exact email match; other text performs case-insensitive partial search across contact fields

Options:

• Limit: Maximum number of results to return per page (default 100, max 100). Use After parameter to paginate for more results
• After: Pagination cursor for fetching next page. Leave empty for first page. Use the NextAfter value from previous response to get next page. Example: 12345678
• Properties: Comma-separated list of contact properties to return. Spaces around commas are allowed and trimmed automatically. Common: email, firstname, lastname, company, phone, jobtitle, website, lifecyclestage (contact lifecycle stage such as lead/MQL/SQL/customer). For full property list, refer to HubSpot documentation. Default: email,firstname,lastname,company,phone

Output:

• Contacts (object-array): Array of contact objects. Each contains: Id (string), Properties (object with requested fields), CreatedAt (ISO 8601 timestamp), UpdatedAt (ISO 8601 timestamp)
• Total (number): Total number of matching contacts found
• HasMore (bool): Whether more results exist beyond current page. If true, use NextAfter to fetch next page
• NextAfter (string): Pagination cursor for next page. Pass to After input parameter to retrieve next page. Empty if no more results
• Hint (string): Actionable recovery suggestion when ErrorMessage is non-empty. Empty on success.
• Retryable (bool): Whether the error is transient and safe to retry immediately. Usually true for StatusCode=500 or OriginalStatusCode=429; otherwise false.
• Summary (string): One-line execution summary for quick context and downstream chaining.
• OriginalStatusCode (number): Upstream HTTP status code (diagnostic-only; do not use it to infer success/failure). 0 means no upstream HTTP response was received (e.g., timeout/network error).
• StatusCode (number): Tool-level status code. 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Primary success/failure signal. Empty string means SUCCESS; non-empty means FAILURE (contains reason and ideally a recovery hint).

Create a Deal

Create a new HubSpot deal with specified properties including deal name, pipeline, stage, amount, close date, and owner, returning the created deal ID and status code.

Input Parameters:

• DealName: Deal name (required). Example: 'Acme Corp - Enterprise License Q1 2024'

Options:

• PipelineId: Pipeline ID. Leave empty to use your HubSpot account's default pipeline. To use a specific pipeline, obtain the Pipeline ID via List Pipelines action (it's a numeric string like '12345678'). When PipelineId is provided, DealStageId becomes required
• DealStageId: Stage ID within the pipeline. Required when PipelineId is set. Common stages: appointmentscheduled (Initial meeting scheduled), qualifiedtobuy (Lead qualified as potential buyer), presentationscheduled (Demo/presentation scheduled), decisionmakerboughtin (Decision maker engaged), contractsent (Contract/proposal sent), closedwon (Deal successfully closed), closedlost (Deal lost/rejected). Note: Available stages depend on your pipeline configuration. Use List Pipelines action to get all stages for a specific pipeline
• Amount: Deal value as numeric string (no currency symbols). Example: '50000'. Currency from HubSpot account settings
• CloseDate: Expected close date. Supports ISO date format 'YYYY-MM-DD' (e.g., '2024-06-30') or Unix timestamp in milliseconds (e.g., '1719705600000'). Recommended: Use ISO date format for better readability
• DealOwner: Owner user ID. Obtain via Get Owners action. Example: '12345678'
• AdditionalFields: Additional deal properties as key-value pairs. All values must be strings. Common fields: description (deal notes/details), deal_currency_code ('USD', 'EUR', 'GBP'), hs_priority ('LOW'/'MEDIUM'/'HIGH'), hs_deal_stage_probability (string '0.0'-'1.0'), hs_forecast_category ('PIPELINE'/'BEST_CASE'/'COMMIT'/'CLOSED'/'OMIT'), hs_next_step (next action description). Use for HubSpot custom properties or fields not covered by standard parameters.
• CheckDuplicate: If true, searches for an existing deal with the EXACT same DealName (case-sensitive) before creating. If a duplicate exists, returns StatusCode=200 with ErrorMessage containing the existing deal ID — no new deal is created. Set to false (default) to skip the check and allow multiple deals with the same name (HubSpot permits this). Note: Duplicate check adds 1 extra API call.

Output:

• DealId (string): Unique ID of the created deal (numeric string like '12345678901'). Use this ID with Update a Deal, Delete Deal, or Get Deals actions. Note: This action only returns the Deal ID. To get full deal details (properties, associations, etc.), use the Get Deals action with this DealId
• OriginalStatusCode (number): Original HTTP status code from HubSpot API. 0=request didn't reach upstream, 201=Created, 401=Auth failed, 429=Rate limited
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter error, 500=System/network error
• ErrorMessage (string): Detailed error message if failed, empty on success

Delete Deal

Permanently deletes one or more HubSpot deals. WARNING: This operation CANNOT be undone. Deleted deals cannot be recovered.

Input Parameters:

• DealId: A single HubSpot deal ID or comma-separated list of IDs to delete. Obtain from Search Deals, Get Deals, or Get Recent Deals actions. Example: '123456' or '123456,789012'

Output:

• AllDeleted (bool): true if all deals were deleted, false if any failed
• FailedItems (object-array): Array of failed deletion objects. Each element: dealId (string), statusCode (number, e.g. 404=Not found, 401=Auth failed, 429=Rate limited), errorMessage (string). Empty if all succeeded
• OriginalStatusCode (number): Last HTTP status code from HubSpot API. 0=Network timeout or connection failed, 204=Deleted, 404=Not found, 429=Rate limited
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for partial failures), -1=Parameter error, 500=System/network error
• ErrorMessage (string): Error details. Empty on full success. Contains summary on partial success (e.g. 'Partial success: 1 deleted, 1 failed') or parameter errors

Get Deals

Retrieve multiple HubSpot deals by their IDs using batch API for efficient processing.

Input Parameters:

• DealIds: Comma-separated deal IDs (required). Obtain from Create a Deal, Search Deals, or Get Recent Deals actions. Example: 12345678901,12345678902

Options:

• Properties: Comma-separated property names (data fields) to return. Default: dealname, amount, dealstage, pipeline, closedate, hubspot_owner_id. All property values are returned as strings.

Output:

• Deals (object-array): Array of deal objects. Each contains: id (string), properties (object - all values are strings), createdAt (ISO 8601), updatedAt (ISO 8601), archived (boolean)
• OriginalStatusCode (number): Original HTTP status code from HubSpot API. 0=didn't reach upstream, 200=Success, 401=Auth failed, 429=Rate limited
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter error, 500=System/network error
• ErrorMessage (string): Error details if failed, empty on success

Get Recent Deals

Retrieve recently modified HubSpot deals. Returns deals sorted by default API order. Use the After parameter for pagination.

Options:

• Limit: Maximum number of deals to retrieve per page (1-100). Default: 100
• After: Pagination cursor for next page. Use the NextCursor value from previous response. Leave empty for first page. Example: '98766'
• Properties: Comma-separated deal property names to return. NO spaces after commas. Common: dealname (title), amount (value as string), dealstage (pipeline stage), pipeline (pipeline ID), closedate (expected close), hubspot_owner_id (owner ID), createdate (creation time), hs_lastmodifieddate (last modified, hs_ prefix = HubSpot system field). Format: 'dealname,amount,dealstage' (correct) vs 'dealname, amount' (wrong - spaces cause errors). For full list, refer to HubSpot documentation. Default: dealname,amount,dealstage,createdate,hs_lastmodifieddate
• Archived: 'false' (default) = active deals only, 'true' = archived deals only

Output:

• Deals (object-array): Array of deal objects. Each contains: id (string, deal unique ID), properties (object, DYNAMIC fields based on Properties input - IMPORTANT: all values are strings including numbers like amount='50000' and dates), createdAt (string, ISO 8601), updatedAt (string, ISO 8601), archived (boolean). Example properties: {"dealname": "Enterprise License", "amount": "50000"}
• Total (number): Number of deals returned in current page
• HasMore (bool): true if more pages available. Use NextCursor value in After parameter to get next page
• NextCursor (string): Pagination cursor for next page. Pass as After input parameter. Empty if no more pages
• OriginalStatusCode (number): Original HTTP status code from HubSpot API. 0=didn't reach upstream, 200=Success, 400=Bad request, 429=Rate limited
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter error, 500=System/network error
• ErrorMessage (string): Error details if failed, empty on success

Search Deals

Search HubSpot deals by keywords (company name, deal title) with customizable properties, sorting, and pagination. When to use: Keyword-based search: Use this action. Get single deal by ID: Use 'Get Deal'. Bulk export by time range: Use 'Get Recent Deals'.

Options:

• Query: Full-text search across deal properties (dealname, etc.). Leave empty to return all deals. Example: 'Acme' or 'Enterprise License'
• Limit: Max deals to return per page (1-100). Default: 50. Use PagingAfter to get more
• Properties: Comma-separated property names to return (no spaces). Common properties: dealname: Deal title, amount: Deal value (returned as string, e.g., '50000'), dealstage: Stage identifier (e.g., 'contractsent', 'qualifiedtobuy'), pipeline: Pipeline identifier (default: 'default'), closedate: Expected close date (ISO 8601), hubspot_owner_id: Owner's HubSpot user ID. Invalid names are silently ignored. For full property list, call 'Get Deal Properties' action or visit HubSpot API documentation. Example: dealname,amount,dealstage,pipeline,closedate,hubspot_owner_id
• SortDirection: Sort by lastmodifieddate. Accepted values (case-sensitive): ASCENDING: Oldest modified deals first, DESCENDING: Newest modified deals first (default). Invalid values will use DESCENDING as fallback.
• PagingAfter: Pagination cursor from previous response. Leave empty for first page. Use PagingAfter value from previous response when HasMore=true to get next page. Example: 'NTI1Cg%3D%3D'

Output:

• Deals (object-array): Array of deal objects. Each contains: id (string): Unique deal identifier, properties (object): Dynamic fields based on Properties input. ALL values are strings (including numbers). Common dealstage values: 'appointmentscheduled', 'qualifiedtobuy', 'contractsent', 'closedwon', 'closedlost'. Common pipeline values: 'default' (standard sales pipeline). createdAt (string): Creation timestamp (ISO 8601). updatedAt (string): Last modification timestamp (ISO 8601). archived (boolean): Whether the deal is archived. Example: {"id": "123", "properties": {"dealname": "Acme License", "amount": "50000", "dealstage": "contractsent"}}
• TotalCount (number): Total matching deals (may exceed Limit - use pagination to get more)
• HasMore (bool): true if more results available. Use PagingAfter value as PagingAfter input parameter to get next page
• PagingAfter (string): Pagination cursor for next page. Pass this value to PagingAfter input parameter to fetch next page. Empty string if no more results
• OriginalStatusCode (number): Original HTTP status code from HubSpot API. 0=didn't reach upstream, 200=Success, 400=Bad request, 429=Rate limited
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter error, 500=System/network error
• ErrorMessage (string): Error details if failed, empty on success

Update a Deal

Update a HubSpot deal by ID. Uses PATCH semantics: only specified properties are changed, others remain unchanged.

Input Parameters:

• DealId: Deal ID to update (required). Obtain from Create a Deal → DealId, Search Deals → Deals[].id, or Get Deals. Example: 12345678901
• Properties: ⚠️ ALL values must be strings, even numbers (e.g. "amount": "75000" not "amount": 75000). Object of deal properties to update (PATCH — only specified fields change). Common fields: dealname (deal title), amount (monetary value as string), dealstage (pipeline stage system ID — e.g. 'appointmentscheduled', 'contractsent', 'closedwon'; get from List Pipelines → stages[].stageId), pipeline (sales pipeline ID; 'default' is the LITERAL ID of HubSpot's built-in pipeline, not a placeholder; use List Pipelines to get custom pipeline IDs), closedate (YYYY-MM-DD, e.g. '2024-06-30'; stored as ISO 8601 datetime), hubspot_owner_id (salesperson ID from Get Owners → results[].id).

Output:

• UpdatedDeal (object): Full deal object after update. Contains: id (string), properties (object with all deal fields including unchanged ones - common keys: dealname, amount, dealstage, pipeline, closedate, hubspot_owner_id, createdate, hs_lastmodifieddate, hs_object_id), createdAt (ISO 8601), updatedAt (ISO 8601), archived (boolean). Note: hs_deal_stage_probability and hs_is_closed are system-computed read-only fields that appear in the response. Do not attempt to set these as input properties — they will be rejected.
• OriginalStatusCode (number): Original HTTP status code from HubSpot API. 0=didn't reach upstream, 200=Updated, 404=Not found, 429=Rate limited
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter error, 500=System/network error
• ErrorMessage (string): Error details if failed, empty on success

Create a Ticket

Create a HubSpot support ticket with specified subject, content, priority, and pipeline stage, optionally associating it with contacts or companies for customer service management. This action intentionally keeps 9 business parameters because ticket creation needs routing fields (Pipeline, PipelineStage), classification fields (Priority, Source), optional association targets (ContactId, CompanyId), and extensibility via AdditionalFields. Only Subject is required; leave unused optional fields empty. ⚠️ HubSpot does not deduplicate tickets natively. To avoid duplicates, search for existing tickets with the same subject using Search Tickets before calling this action.

Input Parameters:

• Subject: Ticket subject/title (required). Brief issue summary. Example: 'Customer unable to login to account'

Options:

• Content: Detailed ticket description with issue details and context (optional). Format: Plain text only (HTML/Markdown not supported). Recommended length: under 5000 characters. Example: 'Customer reports error when attempting to login. Browser: Chrome 120.'
• Pipeline: Ticket pipeline ID (workflow template for ticket handling flow, e.g. technical support flow). Leave empty to use account default pipeline (usually '0'). If you use multiple pipelines, obtain ID from List Pipelines action. Example: '0'
• PipelineStage: Pipeline stage ID. WARNING: Defaults to '1' (New) if left empty. For custom pipelines, this default may be invalid. Default pipeline meanings: 1=New (new ticket), 2=Waiting on Contact (waiting customer reply), 3=Waiting on Us (waiting internal processing), 4=Closed (resolved/closed). For custom pipelines, always get stage IDs from List Pipelines action
• Priority: Ticket priority level (case-insensitive, converted to uppercase). Supported values: HIGH (urgent), MEDIUM (standard), LOW (non-urgent). Only these three values are supported by HubSpot, invalid values will be ignored. If empty, uses HubSpot account default setting (typically no priority assigned)
• Source: How the ticket was submitted: EMAIL (email), PHONE (phone call), CHAT (live chat), WEB_FORM (website form), API (automated/system-created). Use uppercase. If empty, uses HubSpot account default setting
• ContactId: Contact ID to associate (optional). For B2C: link to individual customer. Can combine with CompanyId. Obtain via Search Contacts Action or Get a Contact Action in this platform. Example: '12345678'
• CompanyId: Company ID to associate (optional). For B2B: link to company account. Can combine with ContactId. Obtain via Find Company Action or Get a Company Action in this platform. Example: '87654321'
• AdditionalFields: Additional ticket properties as key-value pairs (object format, not JSON string). Common fields: hs_ticket_category (ticket category, e.g. 'Technical Issue', 'Billing Question', 'Feature Request'), hs_resolution (resolution description text), hs_num_times_contacted (contact count as string, e.g. '3'). Example: {"hs_ticket_category": "Technical Issue", "hs_resolution": "Password reset sent"}

Output:

• TicketId (string): Unique ID of the created ticket (numeric string). Use in Update/Delete/Get Ticket actions. Example: '9876543210'
• TicketProperties (object): Created ticket properties object. CRITICAL: ALL field values are returned as strings by HubSpot API, including numeric IDs (hs_pipeline='0', hs_pipeline_stage='1') and dates (createdate='2024-01-15T10:30:00.000Z'). Fields: subject (string), content (string), hs_pipeline (string), hs_pipeline_stage (string), hs_ticket_priority (string: HIGH/MEDIUM/LOW), source_type (string), hs_ticket_category (string), createdate (string, ISO 8601)
• Associations (object): Ticket associations object. When associations exist: {contacts: {results: [{id: '12345678', type: 'ticket_to_contact'}]}, companies: {results: [{id: '87654321', type: 'ticket_to_company'}]}}. CRITICAL: When NO associations exist, returns empty object {} (NOT null, NOT empty array [], NOT {contacts: {results: []}})
• Hint (string): Actionable next step for the caller when follow-up is needed after this action. Empty string on success with nothing else to do.
• Retryable (bool): Whether the same request can be retried immediately without changing parameters. Usually true only for transient network or rate-limit issues.
• Summary (string): One-line execution summary for quick context, downstream chaining, and fast human review of the result.
• OriginalStatusCode (number): Original HTTP status code from HubSpot API. 0=request didn't reach upstream, 201=Created, 401=Auth failed, 429=Rate limited
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System/network error
• ErrorMessage (string): Detailed error message when the request or upstream business operation fails. Empty string means the action completed successfully.

Delete Tickets

Delete or archive HubSpot tickets by ID with batch support. WARNING: Must set Confirm=true to execute deletion or archive. WARNING: When UseArchive=false, tickets are PERMANENTLY DELETED and CANNOT be recovered. Default (UseArchive=true) archives to recycling bin (restorable within 90 days). Each ticket is verified before deletion. API COST: 2 API calls per ticket (GET verify + DELETE). For large batches (>50), split to avoid rate limiting.

Input Parameters:

• TicketId: ⚠️ API COST: 2 calls per ticket (verify + delete). Batch of 100 tickets consumes about 200 API calls. HubSpot ticket ID(s) to delete (required). Single ID or comma-separated list. Obtain from Get Tickets or Get a Ticket actions and use the Id field from the response. Example: '987654321' (single) or '123,456,789' (batch)

Options:

• UseArchive: Whether to archive instead of permanent delete. Default true (RECOMMENDED). When true, restore from HubSpot Settings > Data Management > Deleted Records within 90 days. When false, PERMANENTLY DELETED.
• Confirm: ⚠️ SAFETY GATE: Must be explicitly set to true to execute deletion or archive. Prevents accidental bulk deletions by Agent.
• IdProperty: ⚠️ ADVANCED OPTION (99% of users should NOT change this): Property to use as identifier (default 'id'). HubSpot supports custom unique properties (for example, external system IDs). Use this only when deleting by one of those custom unique properties instead of HubSpot's internal Id. WARNING: Using an incorrect property may cause deletion to fail with 404 errors.

Output:

• AllDeleted (bool): true if all tickets were deleted/archived, false if any failed
• FailedItems (object-array): Array of failed deletion objects. Empty array if all succeeded. Schema: each object contains TicketId (string, the ticket ID that failed), Reason (string, error description such as 'Ticket not found (HTTP 404)'), and RetryAfterSeconds (number, optional, only present for rate limit errors).
• OriginalStatusCode (number): Last HTTP status code from HubSpot API. 0=Network timeout or connection failed, 204=Deleted, 404=Not found, 429=Rate limited
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for partial failures), -1=Parameter error, 500=System/network error
• ErrorMessage (string): Error details. Empty on full success. Contains summary on partial success (e.g. 'Partial success: 1 succeeded, 1 failed') or parameter errors

Get Tickets

Retrieve HubSpot tickets by ID with batch support, customizable properties, associations, and change history. Common Properties Explained: [Core] subject (ticket title), content (detailed description). [Workflow] hs_pipeline (pipeline ID - which department/workflow handles the ticket, e.g. 'Support' vs 'Sales'), hs_pipeline_stage (current stage in the workflow, e.g. 'New' → 'In Progress' → 'Waiting on Customer' → 'Resolved'). [Priority] hs_ticket_priority (urgency: HIGH/MEDIUM/LOW), hs_ticket_category (issue type). [Origin] source_type (how created: EMAIL/CHAT/FORM/PHONE), hubspot_owner_id (assigned agent ID). [Timestamps] createdate, hs_lastmodifieddate.

Input Parameters:

• TicketIds: Ticket IDs to retrieve. Format: single ID (e.g. '9876543210') or comma-separated list (e.g. '123,456,789'). Maximum 100 IDs per request (HubSpot API limit). For larger batches, split into multiple calls. Supports comma-separated lists. Spaces around commas are automatically trimmed. Obtain from: Create a Ticket (output field: TicketId), Get Tickets (output field: Tickets[].id), or Search Tickets (output field: Results[].id).

Options:

• Properties: Comma-separated ticket property names to retrieve. If empty, defaults to 10 core fields: subject, content, hs_pipeline, hs_pipeline_stage, hs_ticket_priority, source_type, hs_ticket_category, createdate, hs_lastmodifieddate, hubspot_owner_id. Full field list: see HubSpot Settings → Objects → Tickets → Properties. All values returned as strings. Example: 'subject,content,hs_ticket_priority'. See Note for field meanings.
• IdProperty: Advanced option (most users leave as default 'id'). Specifies which field to use when looking up tickets. Default: HubSpot internal ticket ID (a long number like '9876543210'). If your team uses a custom ticket number field (e.g. 'TICKET-2024-001'), enter that field's internal name here. To find a field's internal name: HubSpot Settings → Objects → Tickets → Properties → click the field → copy 'Internal name'.
• IncludeAssociations: Whether to include associated contacts, companies, and deals linked to each ticket. Default: false. Enable this when you need to know which customer (contact), which company, or which sales opportunity (deal) is related to this ticket. Useful for cross-referencing customer information or tracking ticket-to-deal relationships.
• PropertiesWithHistory: Comma-separated properties to include change history (with timestamps and who made the change). Useful for tracking status changes, priority escalations, or ownership transfers. Common: hs_pipeline_stage, hs_ticket_priority, hubspot_owner_id. Example: 'hs_pipeline_stage,hs_ticket_priority'. Leave empty to skip. Returns structure: see Tickets output propertiesWithHistory field.

Output:

• Tickets (object-array): Array of ticket objects. Each contains: id (string), properties (object - key-value pairs of requested fields; IMPORTANT: all values are strings even for numeric or date fields. Common enum values: hs_ticket_priority (HIGH/MEDIUM/LOW), source_type (EMAIL/CHAT/FORM/PHONE/API). Stage values depend on your pipeline configuration. Example: priority returns 'HIGH' not enum, dates return '2024-01-15T10:30:00.000Z' not Date object), propertiesWithHistory (object - only when PropertiesWithHistory is specified; structure: {propertyName: [{value: string (new value after change), timestamp: string (ISO 8601), sourceId: string (who made the change)}]}), createdAt (ISO 8601), updatedAt (ISO 8601), archived (boolean)
• FailItems (object-array): Array of failed retrieval objects (object-array). Each element contains: TicketId (string, the ticket ID that failed), StatusCode (number, HTTP status code e.g. 404=Not found, 401=Unauthorized), ErrorMessage (string, detailed error from HubSpot API). Empty array if all tickets retrieved successfully. Example: [{"TicketId": "invalid_id", "StatusCode": 404, "ErrorMessage": "Ticket not found"}]
• Associations (object-array): Array of ticket-to-object association mappings (only when IncludeAssociations=true). Structure: [{ticketId: {contacts: {results: [{id, type}]}, companies: {results: [{id, type}]}, deals: {results: [{id, type}]}}}]. Access examples: Associations[0]['9876543210'].contacts.results[0].id → first contact ID; Associations[0]['9876543210'].companies.results[*].id → all company IDs. Empty array if IncludeAssociations=false
• OriginalStatusCode (number): Original HTTP status code from HubSpot API. 0=Network timeout or connection failed, 200=Success, 401=Auth failed, 404=Not found, 429=Rate limited
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for partial failures), -1=Parameter error, 500=System/network error
• ErrorMessage (string): Error details if failed, empty on success

Update a Ticket

Update a HubSpot ticket by ID using PATCH (partial update). Only provided fields are changed, other fields remain unchanged. Supports standard properties and custom properties. Core fields: Subject, Content, PipelineStage. Classification fields: Priority (HIGH/MEDIUM/LOW), Source (EMAIL/FORM/PHONE/CHAT/BOT/API), Category, Resolution. Advanced: CustomProperties (object, for non-standard fields), IdProperty (for alternate ID lookup).

Input Parameters:

• TicketId: Ticket ID to update (required). Obtain from Create a Ticket → TicketId, Get Tickets, or Search. Example: 9876543210

Options:

• Subject: Updated ticket subject/title (optional)
• Content: Updated ticket description (optional)
• PipelineStage: Updated stage ID: 1=New, 2=Waiting on Contact, 3=Waiting on Us, 4=Closed. Use List Pipelines (ObjectType=tickets) for custom stages
• Priority: Updated priority: HIGH (urgent), MEDIUM (standard), LOW (non-urgent). Invalid values are ignored and a warning is returned in ErrorMessage.
• Source: Updated source channel: EMAIL, FORM, PHONE, CHAT, BOT, API
• Category: Updated ticket category. Common HubSpot default values: BILLING, PRODUCT, FEATURE_REQUEST, SUPPORT, GENERAL. Custom pipelines may have different category values. Leave empty to keep current category.
• Resolution: Action taken to resolve the ticket (optional)
• CustomProperties: Additional properties object for fields not exposed as dedicated parameters. Example: {"hubspot_owner_id": "12345"}. Property names must match HubSpot internal names
• IdProperty: ⚠️ ADVANCED OPTION (99% of users should NOT change this): How to identify the ticket. Default 'id' uses HubSpot's internal ID. Only change if looking up by a custom unique property (e.g., 'hs_ticket_id'). WARNING: Using an incorrect property will cause the update to fail with 404 errors.

Output:

• TicketId (string): ID of the updated ticket (numeric string). Example: 9876543210
• UpdatedProperties (string-array): Array of HubSpot property names that were changed. Example: ['hs_pipeline_stage', 'hs_ticket_priority']
• TicketProperties (object): Ticket's full properties object after update. Contains both changed and unchanged fields. Core fields: subject (string, title), content (string, description), hs_pipeline_stage (string, stage ID), hs_ticket_priority (string, HIGH/MEDIUM/LOW), source_type (string, channel), hs_ticket_category (string), hs_resolution (string), createdate (string, ISO 8601), hs_lastmodifieddate (string, ISO 8601). All property values within TicketProperties are strings (HubSpot API convention).
• Hint (string): Actionable recovery suggestion when ErrorMessage is non-empty. Empty on success.
• Retryable (bool): Whether the error is transient and safe to retry immediately. Usually true for StatusCode=500 or OriginalStatusCode=429; otherwise false.
• Summary (string): One-line execution summary for quick context and downstream chaining.
• OriginalStatusCode (number): Upstream HTTP status code (diagnostic-only; do not use it to infer success/failure). 0 means no upstream HTTP response was received (e.g., timeout/network error).
• StatusCode (number): Tool-level status code. 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Primary success/failure signal. Empty string means SUCCESS; non-empty means FAILURE (contains reason and ideally a recovery hint).

Create an Engagement

⚠️ HIGH RISK WRITE OPERATION: creates permanent HubSpot engagement records and cannot be undone by this action. Confirm=true is required before execution. Engagements are created with active=true and can trigger HubSpot workflows. EMAIL type only logs activity and does NOT send emails. IdempotencyKey is only a duplicate-detection tag and does NOT prevent duplicate creation on retry.

Input Parameters:

• Confirm: Safety confirmation for write operation. Must be true to create engagement. Use false for dry planning only. Example: true

Options:

• EngagementType: Type of engagement to create: NOTE (internal note/comment), EMAIL (email activity record - does NOT send emails, only logs activity), CALL (phone call record), MEETING (meeting record), TASK (to-do item). Each type requires different Metadata fields. Default: NOTE
• Timestamp: When the engagement occurred, as Unix timestamp in milliseconds (string). Leave empty or '0' to use current time. Conversion tip: use epochconverter.com or convert datetime to milliseconds. Example: '1704067800000' = 2024-01-01 00:30:00 UTC
• OwnerId: HubSpot user ID of the engagement owner (string). Leave empty or "0" to automatically use the authenticated user. Obtain from: HubSpot Settings (⚙️) > Users & Teams > click user name to view ID in URL, or call Get Owners action. Example: "12345678"
• Metadata: Engagement metadata object (varies by EngagementType). NOTE: {"body": "Meeting notes"}. EMAIL (activity log only, does NOT send): {"subject": "Follow-up", "body": "Discussed pricing", "from": {"email": "sales@company.com"}, "to": [{"email": "customer@example.com"}]}. CALL: {"body": "Call summary", "durationMilliseconds": 1800000, "status": "COMPLETED"} where status is COMPLETED(done), BUSY(line busy), NO_ANSWER(no answer), FAILED(call failed), CANCELED(canceled), IN_PROGRESS(ongoing). MEETING: {"body": "Q1 review", "startTime": 1704067800000, "endTime": 1704071400000}; startTime/endTime are Unix timestamps in milliseconds. TASK: {"body": "Task description", "status": "NOT_STARTED"} where status is NOT_STARTED, IN_PROGRESS, COMPLETED, WAITING(blocked), DEFERRED(postponed).
• Associations: CRM object IDs to associate. Structure: {"contactIds": [101], "companyIds": [501], "dealIds": [1001]}. How to get IDs: run Search Contacts/Companies/Deals, then from each returned item take its id field (for example, each object in Contacts has an id). All arrays are optional
• IdempotencyKey: Anti-duplicate marker (optional). If you worry about timeout causing repeated creation, provide a unique value (for example workflow_id + timestamp). System prepends [IDKEY:xxx] to metadata.body for later deduplication search. This does NOT prevent duplicate API retries.

Output:

• EngagementId (string): Unique ID of the created engagement (numeric string, e.g. 987654321). Use in Get Engagement or Delete Engagement actions
• EngagementData (object): Complete engagement data object. Structure: engagement (object: id, type, timestamp, ownerId, active, createdAt, lastUpdated), associations (object: contactIds[], companyIds[], dealIds[], ownerIds[] where ownerIds is usually empty), metadata (object with type-specific fields).
• Success (bool): Boolean indicating whether the engagement was created successfully
• OriginalStatusCode (number): Original HTTP status code from HubSpot API. 0 if request did not reach upstream. 200=Success, 401=Auth failed, 429=Rate limited
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System/network error
• ErrorMessage (string): Detailed error message if failed, empty string on success

Delete Engagements

WARNING: Deletion is PERMANENT and cannot be undone. Deleting an engagement removes it from associated contacts, companies, and deals, but does NOT delete the associated records themselves. API COST: Each engagement requires 2 API calls (GET verify + DELETE), e.g., deleting 10 engagements = 20 API calls. For large batches (>50), split into smaller batches to avoid hitting HubSpot's request limit (HTTP 429).

Input Parameters:

• EngagementIds: Engagement ID(s) to delete (required). Format: numeric string (e.g., '987654321'). Single ID or comma-separated list (supports comma-separated lists). Where to get IDs: Use Create an Engagement, Get an Engagement, or Get Many Engagements actions. Example: '987654321' or '123,456,789'

Output:

• AllDeleted (bool): true if all engagements were deleted, false if any failed
• FailedItems (object-array): Array of failed deletion objects. Each element: EngagementId (string, the ID that failed), Reason (string, e.g. 'Engagement not found (HTTP 404)', 'Rate limited'). Empty if all succeeded
• OriginalStatusCode (number): Last HTTP status code from HubSpot API. 0=Network timeout, 204=Deleted, 401=Auth failed, 404=Not found (may already be deleted), 429=Rate limited (wait and retry), 500=Server error
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for partial failures), -1=Parameter error, 500=System/network error
• ErrorMessage (string): Error details. Empty on full success. Contains summary on partial success (e.g. 'Partial success: 1 of 2 engagements deleted') or parameter errors

Get Engagements

Retrieve HubSpot engagements with configurable pagination and optional bulk fetching capabilities.

Options:

• Limit: Maximum number of engagements per request (default: 100, max: 100)
• GetAll: ⚠️ Advanced Option: Automatically fetch ALL engagements by handling pagination internally. Performance Warning: may take 5-30 minutes for 10,000+ records; stops after 500 API calls (~50,000 records). For regular use keep this false and use After/NextOffset for manual pagination. Default: false
• After: Pagination offset for next page. Use the NextOffset value from previous response. Set to 0 for first page. Example: 100

Output:

• Engagements (object-array): Array of engagement objects. Each object contains: engagement (object — id: number, type: string e.g. NOTE/CALL/EMAIL/MEETING/TASK, timestamp: number Unix ms, ownerId: number, active: boolean, createdAt: number Unix ms, lastUpdated: number Unix ms), associations (object — contactIds: number[], companyIds: number[], dealIds: number[]), metadata (object — body: string for NOTE/CALL, durationMilliseconds: number for CALL, subject: string for EMAIL/MEETING)
• HasMore (bool): true if more pages available. Use NextOffset value in After parameter to get next page
• NextOffset (number): Offset for next page. Pass as After input parameter to retrieve next page. 0 if no more pages
• RequestCount (number): Number of API requests made (relevant when GetAll=true)
• Success (bool): true if operation completed successfully
• Total (number): Number of engagement records returned in this response
• OriginalStatusCode (number): Last HTTP status code from HubSpot API. 0=didn't reach upstream, 200=Success, 401=Auth failed, 429=Rate limited
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter error, 500=System/network error
• ErrorMessage (string): Error details if failed, empty on success

Get an Engagement

Retrieve a specific HubSpot engagement by ID, returning detailed engagement data including metadata, associations, and activity information.

Input Parameters:

• EngagementId: Unique engagement ID to retrieve (required). Obtain from Create an Engagement → EngagementId, Get Many Engagements → Engagements[].engagement.id, or workflow outputs. Example: '987654321'

Output:

• Engagement (object): Engagement core data object. Contains: id (number), type (NOTE/EMAIL/CALL/MEETING/TASK), timestamp (Unix ms), ownerId (number), active (boolean), createdAt/updatedAt (Unix ms).
• Associations (object): Associated CRM objects. Contains: contactIds, companyIds, dealIds, ownerIds, ticketIds (all number arrays).
• Metadata (object): Type-specific metadata object. NOTE: body. EMAIL: subject, body, from, to. CALL: body, durationMilliseconds, status. MEETING: body, startTime, endTime. TASK: body, status, priority.
• OriginalStatusCode (number): Original HTTP status code from HubSpot API. 0=didn't reach upstream, 200=Found, 404=Not found, 429=Rate limited
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter error, 500=System/network error
• ErrorMessage (string): Error details if failed, empty on success

Add Contacts to List

IMPORTANT: This operation does NOT trigger HubSpot workflows by default. Add multiple contacts to a HubSpot list with batch processing and detailed error handling. Batch Limit: Max 100 contacts per request. Contacts already in the list are skipped by HubSpot and may appear in FailedContacts depending on upstream response.

Input Parameters:

• ListId: ⚠️ IMPORTANT: Only manually managed lists support adding contacts. Smart lists (auto-updating) cannot be modified via API. HubSpot list ID (required). How to get: 1) Open HubSpot > Contacts > Lists and copy the list ID in URL. 2) Use Get Many Lists or Search Lists action. Example: '12345678'
• ContactIds: Contact IDs to add (required). Accepts string-array of numeric string IDs. Max 100 per request. Obtain from Create a Contact, Search Contacts, or Get Many Contacts actions. Example: ['87654321', '87654322', '87654323']

Output:

• AddedContacts (number): Number of contacts successfully added to the list
• FailedContacts (object-array): Array of failed contact objects (object-array). Each object contains: ContactId (string): failed contact ID, Reason (string): failure reason. Empty array if all contacts were added successfully
• Success (bool): Whether at least one contact was successfully added. Note: Success=true does NOT mean all contacts were added. Check FailedContacts for details.
• ResponseData (object): Raw response object from HubSpot API (object). Contains: recordsIdsAdded (string-array): successfully added contact IDs, recordIdsMissing (object-array): failed contact objects with recordId and error.message
• OriginalStatusCode (number): The original HTTP status code returned by the HubSpot API. Default 0 means the request did not reach upstream (e.g., timeout or parameter error). Common values: 200=OK, 400=Bad request, 401=Unauthorized, 404=List not found, 429=Rate limited. Use for debugging.
• StatusCode (number): Tool-level status code. 200=request completed and response parsed (not equal to full success), -1=local parameter validation error (do not retry), 500=local system/network error (may retry). Check ErrorMessage and FailedContacts for partial failures
• ErrorMessage (string): Error message if the operation failed, otherwise empty

Create a List

Create a HubSpot list (segment). For list-membership APIs such as Add Contacts to List and Delete Contacts from List, use MANUAL or SNAPSHOT lists; DYNAMIC lists are filter-driven and cannot be edited via memberships APIs. This action includes a best-effort pre-check for same-name lists to improve retry idempotency.

Input Parameters:

• ListName: Name of the list to create (required, must be unique in portal). Retry-safe tip: use a unique suffix (for example workflow ID or timestamp) to avoid name collisions. Example: 'GI Integration Test List 20260417'.

Options:

• ObjectTypeId: Object type ID the list stores. Default '0-1' for contacts. Common built-in values: 0-1=contacts, 0-2=companies, 0-3=deals, 0-5=tickets. How to obtain: 1) for built-in objects, use the fixed values listed here directly; 2) for custom objects, read the object type from HubSpot UI Settings > Objects > Custom Objects; 3) via API, call HubSpot CRM object metadata/schema APIs and use the returned objectTypeId such as 2-1234567.
• ProcessingType: List processing type. Allowed: MANUAL, SNAPSHOT, DYNAMIC. MANUAL: manually managed members, supports Add/Remove memberships APIs. SNAPSHOT: static member snapshot. DYNAMIC: filter-driven auto-updating members, memberships APIs are not supported. Recommendation: use MANUAL for integration workflows.
• ListFolderId: Optional HubSpot list folder ID. Leave empty to create in root folder. How to obtain: 1) HubSpot UI: Lists > Folders, then read folder ID from URL. 2) API: call a list-folder endpoint if available in your tenant. Example: "12345".

Output:

• ListId (string): Created list ID (ILS ID), normalized as string for contract consistency.
• ListName (string): Name of the list that HubSpot created or returned after the request completed successfully.
• ObjectTypeId (string): Object type ID that determines which HubSpot record type this list stores, such as contacts, companies, deals, or tickets.
• ProcessingType (string): List processing mode returned by HubSpot, such as MANUAL, SNAPSHOT, or DYNAMIC, which determines how memberships behave.
• ProcessingStatus (string): Current HubSpot processing status for the list, such as COMPLETE or PROCESSING, so callers know whether the list is ready to use.
• ResponseData (object): Normalized list object from HubSpot response.list. Core fields: listId (string), name (string), objectTypeId (string), processingType (string), processingStatus (string), createdAt (ISO 8601), updatedAt (ISO 8601).
• Hint (string): Actionable next step for the caller when follow-up is needed after this action. Empty string on success with nothing else to do.
• Retryable (bool): Whether the same request can be retried immediately without changing parameters. Usually true only for transient network or rate-limit issues.
• Summary (string): One-line execution summary for quick context, downstream chaining, and fast human review of the result.
• OriginalStatusCode (number): Original upstream HTTP status code from HubSpot. 0 means request didn't reach upstream.
• StatusCode (number): Tool-level status code. 200=request processed, -1=local parameter validation error, 500=local network/system error.
• ErrorMessage (string): Detailed error message when list creation fails or HubSpot returns a business error. Empty string means the request completed successfully.

Delete Contacts from List

Remove contacts from a HubSpot list membership. Takes effect immediately and cannot be undone (no recycle bin). Contacts remain in CRM records and can be re-added later. Batch limit: HubSpot supports up to 100 contacts per request; split larger batches.

Input Parameters:

• ListId: ⚠️ Static lists only. HubSpot list ID (required). Only manually managed static lists support membership updates; dynamic/rule-based lists do not. Obtain from HubSpot UI or list-related actions. Example: '12345678'
• ContactIds: Comma-separated contact IDs to remove (required). Supports comma-separated lists; spaces around commas are automatically trimmed. IDs are numeric strings, typically 8-10 digits. Max 100 contacts per request. Obtain from Search/Get/Create contact actions. Example: '87654321, 87654322, 87654323'

Output:

• RemovedContacts (number): Number of contacts successfully removed
• FailedContacts (object-array): Array of failed contact objects (object-array). Each object contains: ContactId (string): contact ID that failed to remove, Reason (string): failure reason such as 'Contact not found' or 'Contact not in list'. Empty array if all succeeded
• Success (bool): true if operation succeeded (some contacts may still have failed - check FailedContacts)
• ResponseData (object): Advanced debugging payload from HubSpot API (object). Contains: recordIdsRemoved (string-array): removed contact IDs, recordIdsMissing (string-array/object-array depending on upstream): contacts not removed
• OriginalStatusCode (number): Original HTTP status code from HubSpot API. 0=didn't reach upstream, 200=Success, 404=List not found, 429=Rate limited
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for partial failures), -1=Parameter error, 500=System/network error
• ErrorMessage (string): Error details if failed, empty on full success

Delete a List

Permanently removes the specified list from normal usage. HubSpot allows restoring deleted lists within 90 days; after that they are purged. This action is destructive and requires Confirm=true.

Input Parameters:

• ListId: HubSpot ILS list ID to delete (required). Example: '611'.

Options:

• Confirm: Safety confirmation. Must be true to execute deletion.

Output:

• Deleted (bool): True if deletion request succeeded (HTTP 204).
• ListId (string): The list ID requested for deletion.
• OriginalStatusCode (number): Original upstream HTTP status code from HubSpot. 0 means request didn't reach upstream.
• StatusCode (number): Tool-level status code. 200=request processed, -1=local parameter validation error, 500=local network/system error.
• ErrorMessage (string): Error details when deletion fails; empty string on success.

List Pipelines

Retrieve HubSpot CRM pipelines with complete configuration details including stages, metadata, and display properties. Use this to discover valid pipeline stage IDs for Create/Update Deal or Ticket actions.

Options:

• ObjectType: Type of CRM pipeline to retrieve. Accepted values: 'deals' (default) = sales pipelines for managing deal stages (e.g. Appointment Scheduled → Contract Sent → Closed Won); 'tickets' = support pipelines for managing ticket statuses (e.g. New → Waiting on Contact → Closed). Any other value defaults to 'deals'. 💡 Use the returned StageId values when setting dealstage in Create/Update Deal, or hs_pipeline_stage in Create/Update Ticket.

Output:

• Pipelines (object-array): Array of pipeline objects. Each pipeline contains: PipelineId (string, use as 'pipeline' param in Create/Update Deal), PipelineName (string), DisplayOrder (number), Archived (boolean), CreatedAt (string ISO 8601), UpdatedAt (string ISO 8601), StageCount (number), Stages (array). Each Stage contains: StageId (string — use as 'dealstage' in Deal actions or 'hs_pipeline_stage' in Ticket actions), StageName (string, human-readable label), DisplayOrder (number), Probability (number 0.0-1.0, deals only), IsClosed (boolean), IsClosedWon (boolean, deals only).
• OriginalStatusCode (number): Original HTTP status code from HubSpot API. 0=didn't reach upstream, 200=Success, 401=Auth failed, 404=Not found
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter error, 500=System/network error
• ErrorMessage (string): Error details if failed, empty on success

5. Example Usage

This section will guide you through creating a simple workflow to add a new company to your HubSpot CRM.

The workflow will consist of three nodes: Start -> Hubspot: Create a Company -> Answer.

Step-by-Step Guide

1. Add the Hubspot Node:
   • In the workflow canvas, click the "+" button to add a new node.
   • In the panel that appears, select the "Tools" tab.
   • Find and select "Hubspot" from the list of tools.
   • In the list of supported operations for Hubspot, click on "Create a Company". This will add the corresponding node to your canvas.
2. Configure the Node:
   • Click on the newly added "Create a Company" node to open its configuration panel on the right.
   • Credentials: At the top of the panel, find the credentials field. Click the dropdown menu and select the Hubspot credential you have already configured.
   • Parameters: Fill in the input parameters for the action.
   • CompanyName: This is a required field. Enter the name for the new company, for example, Innovate Corp.
   • CompanyDomain: This is an optional but recommended field. Enter the company's website domain, such as innovatecorp.com.
   • Phone: You can also add other details like a phone number, e.g., +1-555-123-4567.
3. Run and Validate:
   • Once all required parameters are correctly filled, any error indicators on the workflow canvas should disappear.
   • Click the "Run" button in the top-right corner of the canvas to execute the workflow.
   • After a successful execution, you can click the log icon (also in the top-right) to view the detailed inputs and outputs of the node, confirming that the operation was successful. You should see a StatusCode of 201 and a new CompanyId in the output.

After completing these steps, your workflow is fully configured. When you run it, a new company record will be created in your HubSpot account.

6. FAQs

Q: I'm receiving a 401 Unauthorized or 403 Forbidden error. What should I do?

A: This typically indicates an issue with your credentials or permissions. Please check the following:

• Ensure your API key or OAuth token is correct and has not expired.
• Verify that the user or app associated with the credentials has the necessary permissions in HubSpot to perform the requested action (e.g., create/edit companies).

Q: Why did my "Create a Deal" operation fail?

A: A common reason for failure is missing or incorrect IDs for the pipeline or deal stage. You can use the List Pipelines operation to retrieve a list of all available pipelines and their corresponding stage IDs. Ensure the DealName field, which is required, is also filled out.

Q: How can I find the ID of a specific contact to add them to a list?

A: You can use the Search Contacts operation. By providing an email address in the Query parameter, you can find the specific contact and retrieve their ContactId from the output.

7. Official Documentation

For more in-depth information about the HubSpot API and its capabilities, please refer to the Hubspot Official API Documentation.