HubSpot AI Agents: API Guide and Governed Automations
Understand HubSpot's native agents and build cross-system deal-risk, campaign, and expansion reviews on Major with scoped access, durable state, and approved CRM writes.

HubSpot AI agents include HubSpot's own customer, prospecting, and data agents, plus agents that work with HubSpot through its APIs. This guide covers the native features, API permissions, and cross-system automations RevOps and marketing operations teams can build on Major, with durable review queues and controlled CRM writes.
What HubSpot is and who relies on it
HubSpot holds the customer records that sales, marketing, and service teams use to coordinate work. Its CRM objects capture transactions, people, companies, and activities; associations connect those records so an opportunity can be understood alongside its account and interactions.
For a sales manager, the central job is tracking an open transaction through its pipeline. HubSpot's deals documentation describes deals as transactions that progress through stages, with properties such as amount, close date, and stage. Marketing operations teams connect campaign context to performance analysis, while account owners need evidence behind proposed follow-up.
Major adds a deterministic app layer around those jobs. An agent can build an app that stores account mappings, risk reviews, and approval history, then run that software for repeatable work. The agent reserves judgment for interpreting contradictory evidence or recommending a next action. HubSpot remains the customer system of record; the Major app holds the operational state needed to coordinate work across systems.
HubSpot AI agents and the built-in features
HubSpot already offers native agents. Its official AI product page describes Customer Agent, Prospecting Agent, Data Agent, and access to agents through Breeze Assistant. These are substantive capabilities, not merely text generation beside a CRM record.
- Customer Agent resolves common inquiries using customer context, with human teams handling cases that need them.
- Prospecting Agent monitors buying signals and supports personalized outreach.
- Data Agent answers questions about contacts and companies using CRM data, calls, emails, and documents.
- Breeze Assistant gives teams an interface for assistance and accessing agents where they work.
Major adds value when the process needs an operational control surface spanning several systems. Examples include combining Gong evidence with HubSpot stages, comparing GA4 measurements with campaign mappings, or tracking Stripe expansion signals through approval and deal creation.
The distinction is where execution and memory live. On Major, the app stores records and runs repeatable comparisons; the agent interprets evidence; the workflow sequences execution and approvals. Evaluate the native features for the work they already cover, then define the cross-system gap precisely before adding another process.
How HubSpot connects to Major
Major has a native HubSpot connector. IT sets up the connection once, scopes access to the required account and operations, and stores credentials centrally in the connector vault. Credentials belong in neither application code nor agent prompts.
The connector's existence does not mean every HubSpot API operation is automatically exposed as an action. Confirm the available connector operations against the process you plan to run, especially a date-versioned endpoint. Keep the approved access boundary narrower than the vendor's full API surface.
A practical rollout starts with read access and an internal review queue. Add write access only after testing the proposed fields, approval policy, and failure behavior. Major's SSO, RBAC, and audit logs govern access across the app, agent, and workflow.
Major orchestrates HubSpot; it never replaces it. Keep ownership, pipeline configuration, and authoritative customer records in HubSpot. Store external identifiers, evidence snapshots, proposed mutations, and execution receipts in the Major app so reviewers can inspect a recommendation without reconstructing an entire conversation.
HubSpot API guide for governed automation
Authentication, scopes, and versions
HubSpot documents OAuth access tokens for multi-account distribution and static access tokens for a single account, sent with Bearer authorization. Legacy private apps also remain documented. A personal access key used by the CLI is not the account API credential to put into a production integration.
Start a pipeline reader with crm.objects.deals.read. Request crm.objects.deals.write only for approved mutations, and marketing.campaigns.read for campaign retrieval. The scope catalog defines these separately. Check each operation's requirements rather than assuming deal write permission covers every activity or associated object.
The paths below reproduce the reference literally. HubSpot's current legacy v3 deal pages use the numeric deal object type, 0-3. The campaign example uses the date-versioned reference. Do not mix path conventions while assembling requests.
Pagination, limits, events, and testing
CRM search accepts limit and after in the request body, with the next cursor returned as paging.next.after. It supports up to 200 records per page, five search requests per second per account, and 10,000 results per query. Partition large reconciliations into bounded windows.
General rate limits depend on distribution and subscription. Marketplace OAuth apps have 110 requests per 10 seconds per installed account, excluding search. Private apps have 100 per 10 seconds on Free or Starter and 190 on Professional or Enterprise; daily account limits are 250,000, 625,000, and 1,000,000 respectively.
Watch X-HubSpot-RateLimit-Remaining, X-HubSpot-RateLimit-Max, and X-HubSpot-RateLimit-Interval-Milliseconds. Daily headers are absent for OAuth responses, and search responses omit these rate-limit headers. Apply separate search throttling.
The webhook guide documents property and association changes, duplicate delivery, and unordered notifications. Failed notifications can be retried up to 10 times over 24 hours, including when acknowledgement exceeds five seconds. Validate the actual signature version using the request validation instructions; v3 uses HMAC SHA-256, a timestamp, and rejection of requests older than five minutes. Legacy signatures use different verification inputs.
For testing, HubSpot provides configurable test accounts that simulate subscription combinations. Test approvals and retries there before enabling production writes.
Find deals needing review
POST /crm/v3/objects/0-3/search retrieves deals matching specified filters and sorting.
- App: populate the review queue with late-stage deals in a defined close-date window.
- Agent: interpret why selected deals look stalled using linked external evidence.
- Workflow: run scheduled searches, page results, and checkpoint completed windows.
Retrieve a deal's current state
GET /crm/v3/objects/0-3/{dealId} reads a deal, with selectable properties, property history, and associated IDs.
- App: display the current amount and stage beside the stored proposal.
- Agent: compare current facts with the evidence behind a risk assessment.
- Workflow: re-read the record immediately before an approved write.
Create an approved opportunity
POST /crm/v3/objects/0-3 creates a deal and returns its ID.
- App: retain the returned ID against the originating billing signal.
- Agent: judge whether an expansion signal warrants a distinct opportunity.
- Workflow: create the approved deal only after duplicate checks and payload validation.
Update selected deal properties
PATCH /crm/v3/objects/0-3/{dealId} partially updates an existing deal.
- App: show a field-level before-and-after preview for the reviewer.
- Agent: recommend a revised next action with supporting evidence.
- Workflow: apply only approved, allowlisted fields and record the result.
Attach an evidence note
POST /crm/v3/objects/notes creates a CRM note, optionally with associations.
- App: hold the proposed text, evidence links, and approval version.
- Agent: draft a concise account brief distinguishing facts from interpretation.
- Workflow: create the approved note, then retain its ID to prevent duplicate posting.
Resolve linked records
GET /crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType} retrieves a record's associations to another object type.
- App: maintain explicit links between a reviewed deal and its company records.
- Agent: identify ambiguous account matches instead of guessing from a similar name.
- Workflow: follow association pagination before constructing the evidence packet.
Read pipeline definitions
GET /crm/v3/pipelines/{objectType} retrieves pipelines for an object type.
- App: map stage IDs to labels in the queue.
- Agent: interpret inactivity relative to the actual pipeline stage.
- Workflow: refresh cached definitions and flag removed or unexpected stages.
Read campaign context
GET /marketing/campaigns/2026-09/{campaignGuid} retrieves a marketing campaign by its internal ID.
- App: retain the campaign identifier alongside a validated GA4 reporting mapping.
- Agent: interpret an anomaly in the context of that campaign's purpose.
- Workflow: refresh campaign context before assembling the daily brief.
HubSpot automation use cases on Major
Deal-risk reviews with HubSpot and Gong
- App: store deal-to-account mappings, call references, open reviews, and owner responses.
- Agent: weigh missing activity against call evidence and distinguish a delayed meeting from a genuine stall.
- Workflow: search the review cohort daily, gather evidence, and route a brief for approval before any CRM mutation.
- Endpoints: deal search, deal retrieval, associations, pipeline definitions, and approved note creation from the API guide.
Campaign anomaly briefs with HubSpot and GA4
- App: maintain campaign-to-report mappings, measurement history, and deterministic baseline calculations.
- Agent: explain whether a conversion drop looks like a source shift, tracking problem, or campaign issue, without claiming causality from correlation.
- Workflow: pull daily measurements and campaign context, then send an internal review brief. Keep the brief in Major unless a separately verified write destination is available.
- Endpoints: campaign retrieval from the API guide. CRM notes are not automatically notes on marketing campaign records.
Expansion reviews with HubSpot and Stripe
- App: store billing-event mappings, existing opportunity IDs, and processed-signal keys.
- Agent: decide whether sustained usage suggests expansion, ordinary seasonality, or insufficient evidence.
- Workflow: check existing deals, request owner approval, and create or update the selected opportunity once.
- Endpoints: deal search, retrieval, creation, and partial update from the API guide.
Start with one of these processes rather than granting a general-purpose writer access to the entire CRM. Give each queue an owner, an evidence freshness policy, and a clear definition of completion.
Architecture: build the review system on Major

Figure 1. HubSpot remains authoritative while Major holds evidence and review state.
Build the app before enabling autonomous execution. Its database needs separate records for source events, account mappings, evidence snapshots, proposals, approvals, and execution attempts. A single mutable summary field cannot explain what happened across several runs.
- Connect: IT configures scoped HubSpot and Gong access in the vault.
- Collect: a schedule or verified event starts the workflow, which fetches current records and linked evidence.
- Persist: deterministic app code normalizes identifiers, calculates elapsed time, and stores the packet.
- Judge: the agent assesses risk and drafts a bounded proposal with evidence references.
- Review: the app displays the proposal, source timestamps, and exact intended changes.
- Execute: the workflow checks approval and freshness, performs the allowed action, and saves the receipt.
Keep routine calculations out of the model. Once the agent has helped build the repeatable software, that app can run the same calculations on later reviews. Judgment stays with the agent; state and repeatable execution stay in software. This is the practical meaning of reason once, run forever.
For example: reviewing 100 deals each week
Consider an illustrative sales operations team reviewing 100 late-stage deals weekly. Suppose opening HubSpot, finding the relevant Gong calls, and writing a short brief takes eight minutes per deal. The manual preparation workload is 100 × 8 = 800 minutes, or 13 hours and 20 minutes.
Now suppose the Major app assembles the evidence automatically, while the agent drafts the assessment. A person spends one minute reviewing each of 80 straightforward briefs and five minutes reviewing each of 20 exceptions. Review time becomes 80 × 1 + 20 × 5 = 180 minutes, or three hours.
The difference is 620 minutes, or 10 hours and 20 minutes of preparation and review time under these assumptions. This is not a customer result, and it excludes setup, maintenance, and infrastructure costs.
For one exception, the agent might find an optimistic close date but a call showing unresolved procurement. It proposes an evidence note, not an automatic stage change. The owner approves the note; the workflow rechecks the deal and records the resulting note ID. Measure actual review time, incorrect flags, and duplicate writes during the pilot before estimating a return.
Governance, approval, and failure handling

Figure 2. Internal analysis can proceed while consequential HubSpot mutations require approval.
An internal brief can be saved without altering HubSpot. Changes to deal amount, ownership, stage, customer-facing messages, and record deletion should require explicit policy and human approval. Never let evidence text from a call or email redefine those permissions.
Bind approval to the exact payload and source version. If the deal changes while a reviewer is considering the proposal, invalidate or refresh the approval rather than writing stale information. Keep rejected proposals and reviewer corrections so operators can improve instructions.
Design recovery deliberately:
- Rate limits: throttle per account and endpoint family, back off with jitter on temporary failures, and pause daily-limit failures instead of retrying continuously.
- Duplicate events: use a composite event fingerprint. HubSpot says the event ID alone is not guaranteed unique in its webhook guide.
- Uncertain writes: reconcile the recorded intent and returned object before retrying a create after a timeout.
- Audit: retain the evidence version, recommendation, approver, payload, execution attempt, and confirmed result.
Webhook limits and the difference from HubSpot workflows
A deal event is an invalidation signal, not a complete account snapshot. Subscribe to deal.propertyChange for the stage property, then retrieve current deal context. If contact properties matter, configure the appropriate contact subscriptions too; a deal subscription does not make every associated record change visible.
The v3 webhook guide documents separate subscription types for property changes and association changes. A relationship being added or removed is different from a property changing on an already linked record. Association notifications can also describe both sides of a relationship, so deduplicate at the business-action level.
Do not carry forward a blanket claim about custom-object webhook entitlement from an older implementation. Verify the chosen webhook generation, supported objects, and account permissions before promising coverage.
The operational distinction is straightforward: rule-based workflow steps fetch, route, and retry; the agent interprets uncertain evidence. A fixed inactivity threshold can select a review candidate, but deciding whether that inactivity signals procurement friction or a normal buying cycle requires judgment. The app records both the threshold result and the agent's reasoning so a person can challenge either.
HubSpot AI Apps, Agents and Workflow Automations
Every published Major use case that works with HubSpot, newest first. Each one names the HubSpot API objects involved and shows the app, agent and workflow split.
- Automate HubSpot GA4 Campaign Anomaly Briefs: Connect HubSpot campaign context to GA4 reporting, then turn meaningful traffic and conversion changes into a reviewable daily brief instead of another manual report.
- HubSpot Gong Integration for Automated Deal-Risk Alerts: Connect HubSpot deal stages with Gong call signals to surface quiet deal risk, preserve the evidence, and route a review before pipeline slippage becomes a surprise.
- AI-Powered No-Code App Builder: From Prompt to Governed App: A prompt can start an app. The real test is whether the result can hold state, connect to business systems and run under the controls your team needs.
- AI Agents for Real Estate: 6 Workflows That Stay Governed: Real estate agents can use AI for lead follow-up, listing operations, transaction coordination, and property management. The durable version runs on governed apps, not a conversation that forgets.
- n8n vs Make vs Zapier: Choosing for Governed Work: Choosing between n8n, Make, and Zapier? Compare how each handles workflow complexity, control, and usage, then see when a governed app layer is the better fit.
- AI Agents for Lead Generation: 6 Workflows to Qualify and Route Leads: Lead generation agents should do more than find names. Map six workflows for enriching, qualifying, routing, and following up on prospects, with repeatable execution in governed apps and human judgment where it counts.
- AI Agents for Marketing: Use Cases, Reporting, and Campaign Ops: Marketing teams use AI agents to automate campaign reporting, flag performance anomalies, and route leads across ad platforms, CRMs, and Sheets. See where they fit and how to build a governed, reusable agent.
- HubSpot Deal Pipeline Workflows: 5 Cross-Tool Jobs That Earn Their Keep: Five HubSpot deal pipeline workflows that pull context from Gong, DocuSign, Apollo and Stripe: stage tracking, call updates, enrichment, risk and handoff.
Frequently asked questions
What are HubSpot AI agents?
They include HubSpot's native customer, prospecting, and data agents, plus external agents that use authorized HubSpot APIs. On Major, an agent interprets context, an app holds durable state and review queues, and a workflow coordinates execution and approvals.
Can AI agents update HubSpot records automatically?
Yes, when the integration has the necessary write permission. On Major, limit automatic changes to explicitly allowed fields and policies. Require approval for consequential mutations, bind approval to the exact payload, and retain the resulting record ID and audit history.
How can you trigger an agent from a HubSpot deal change?
Configure a deal.propertyChange subscription for the stage property. Verify the incoming request, persist and deduplicate the event, then retrieve the current deal and related context before invoking the agent. The notification is not a complete account snapshot.
How does an AI agent differ from a HubSpot Workflow?
Fixed workflow logic handles predictable conditions and actions. An agent interprets nuanced evidence, such as whether a call reveals a genuine buying obstacle. Major combines agent judgment with deterministic app state, workflow routing, and human approval where policy requires it.
Does Major have a native HubSpot connector?
Yes. Major has a native HubSpot connector configured once by IT, with centrally stored credentials and scoped access. Confirm the connector exposes the operations needed for your process rather than assuming every documented HubSpot endpoint is available automatically.
What are the limits of HubSpot webhooks for agents?
Subscriptions distinguish object properties from relationship changes. Notifications can arrive out of order or more than once, and related-record context may need additional reads. Use the selected webhook generation's documentation for object support, signature validation, and delivery behavior.
Sources
- HubSpot API overview and versioned reference entry point.
- HubSpot's native AI agents, customer service, prospecting, and data assistance.
- Authentication overview: OAuth, static access tokens, and developer authentication distinctions.
- Scope catalog defining granular CRM read, write, and campaign permissions.
- API usage guidelines covering account limits, distribution, headers, and exceptions.
- CRM search guide covering pagination, filtering, result ceilings, and search throttling.
- Webhook guide covering subscriptions, duplicate delivery, ordering, testing, and retries.
- Request validation instructions for signature versions and timestamp verification.
- Configurable test accounts for subscription-specific integration testing.
- Search deals endpoint reference.
- Read a deal endpoint reference.
- Create a deal endpoint reference.
- Update a deal endpoint reference.
- Create a note endpoint reference.
- Retrieve record associations endpoint reference.
- Retrieve pipeline definitions endpoint reference.
- Retrieve a campaign date-versioned endpoint reference.
Start building on Major
Build a HubSpot review app with evidence history, an agent for judgment, and a workflow that checks approval before writing. Start with one queue and a scoped connector.
About the author
Ritvij Gautam is Head of Growth at Major.
Last reviewed November 20, 2026 by Ritvij Gautam.
Frequently asked questions
- What are HubSpot AI agents?
- They include HubSpot's native customer, prospecting, and data agents, plus external agents that use authorized HubSpot APIs. On Major, an agent interprets context, an app holds durable state and review queues, and a workflow coordinates execution and approvals.
- Can AI agents update HubSpot records automatically?
- Yes, when the integration has the necessary write permission. On Major, limit automatic changes to explicitly allowed fields and policies. Require approval for consequential mutations, bind approval to the exact payload, and retain the resulting record ID and audit history.
- How can you trigger an agent from a HubSpot deal change?
- Configure a deal.propertyChange subscription for the stage property. Verify the incoming request, persist and deduplicate the event, then retrieve the current deal and related context before invoking the agent. The notification is not a complete account snapshot.
- How does an AI agent differ from a HubSpot Workflow?
- Fixed workflow logic handles predictable conditions and actions. An agent interprets nuanced evidence, such as whether a call reveals a genuine buying obstacle. Major combines agent judgment with deterministic app state, workflow routing, and human approval where policy requires it.
- Does Major have a native HubSpot connector?
- Yes. Major has a native HubSpot connector configured once by IT, with centrally stored credentials and scoped access. Confirm the connector exposes the operations needed for your process rather than assuming every documented HubSpot endpoint is available automatically.
- What are the limits of HubSpot webhooks for agents?
- Subscriptions distinguish object properties from relationship changes. Notifications can arrive out of order or more than once, and related-record context may need additional reads. Use the selected webhook generation's documentation for object support, signature validation, and delivery behavior.