HubSpot Automation Actions V4
Browse all Hubspot APIs46
AI ReadinessFoundational (D)46/100
Official vendor OpenAPI document · agent-readyMarketingMarketing Automationoauth2, apiKey16 EndpointsREST
For Agents
Create custom workflow action definitions, attach execution functions, manage action revisions, and complete automation callbacks. Enables extending HubSpot workflows with external service integrations across 16 endpoints.
Use for: I need to create a custom workflow action for my HubSpot app, I want to attach a function to an automation action definition, List all custom action definitions for my app, Get the revision history for a specific action definition
Not supported: Does not handle workflow creation, contact record management, or email sending - use for custom workflow action definition, function attachment, and callback completion only.
Define and manage custom workflow actions that extend HubSpot's automation tool with external service integrations. Supports 16 endpoints for creating action definitions, attaching serverless functions to action steps, managing definition revisions, and completing workflow callbacks. Enables developers to build reusable automation actions that HubSpot users can configure within their workflows to call external services, process data, and return results back to the workflow execution context.
Install Jentic One Beta
Connect the Automation Actions V4 to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Automation Actions V4, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fhubspot.com%2Fhubspot-automation-actions-v4" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fhubspot.com%2Fhubspot-automation-actions-v4" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Automation Actions V4 API.
Define custom workflow actions with typed input fields, output properties, and execution functions that HubSpot users configure in the workflow editor
Attach serverless functions to action definitions that execute when a workflow reaches the custom action step
Complete single and batch workflow callbacks to return execution results back to the HubSpot workflow engine
Version action definitions with revision tracking to manage updates without breaking active workflows
Configure function types (pre-action, post-action, fetch) for different stages of the action execution lifecycle
Use Cases
Patterns agents use Automation Actions V4 API for, with concrete tasks.
★ AI Agent Workflow Extension Development
AI agents use the Automation Actions V4 API through Jentic to programmatically create and manage custom HubSpot workflow actions. The agent searches for 'create custom workflow action' via Jentic, receives the POST /automation/v4/actions/{appId} operation schema with required fields (actionUrl, published, labels, inputFields), and creates the action definition. This enables building custom integrations that HubSpot users drag into their workflows without the agent needing to navigate HubSpot's developer portal. Integration takes under an hour through Jentic versus 2-3 days for direct OAuth app setup and function deployment.
Create a new custom action definition for app ID 12345 with an input field 'email' of type string and an action URL pointing to the external service endpoint
Serverless Function Attachment
Attach execution functions to custom action definitions via PUT /automation/v4/actions/{appId}/{definitionId}/functions/{functionType}. Functions execute when a HubSpot workflow reaches the custom action step. The API supports multiple function types for different execution stages - pre-action validation, main execution, and post-action processing. Functions can be updated independently of the action definition, enabling iterative development without republishing the entire action.
Attach a POST_ACTION_EXECUTION function to action definition ID 'def-456' for app ID 12345, then verify the function was registered by retrieving it
Workflow Callback Completion
Complete workflow callbacks via POST /automation/v4/actions/callbacks/{callbackId}/complete when custom actions finish processing asynchronously. The callback returns output properties back to the HubSpot workflow engine, allowing subsequent workflow steps to use the custom action's results. Batch callback completion at /automation/v4/actions/callbacks/complete handles multiple concurrent workflow executions efficiently, critical for high-volume automation scenarios processing thousands of enrolled contacts.
Complete callback ID 'cb-789' with output properties including 'enriched_email' and 'score' values, then verify the callback was acknowledged
Action Definition Version Management
Track and retrieve action definition revisions via GET /automation/v4/actions/{appId}/{definitionId}/revisions. Each update to an action definition creates a new revision, enabling rollback and audit of changes. Active workflows reference specific revisions, so updating a definition creates a new version without disrupting running workflows. Revision history enables controlled deployment of action changes across production workflow environments.
Retrieve all revisions for action definition 'def-456' under app 12345, identify the latest revision ID, and compare its input fields to the previous version
Key Endpoints
16 endpoints — define and manage custom workflow actions that extend hubspot's automation tool with external service integrations.
METHOD
PATH
DESCRIPTION
POST
/automation/v4/actions/{appId}
Create a custom action definition
GET
/automation/v4/actions/{appId}
List all action definitions for an app
GET
/automation/v4/actions/{appId}/{definitionId}
Get a specific action definition
PATCH
/automation/v4/actions/{appId}/{definitionId}
Update an action definition
PUT
/automation/v4/actions/{appId}/{definitionId}/functions/{functionType}
Attach a function to an action
POST
/automation/v4/actions/callbacks/{callbackId}/complete
Complete a workflow callback
POST
/automation/v4/actions/callbacks/complete
Batch complete callbacks
GET
/automation/v4/actions/{appId}/{definitionId}/revisions
List action definition revisions
POST
/automation/v4/actions/{appId}
Create a custom action definition
GET
/automation/v4/actions/{appId}
List all action definitions for an app
GET
/automation/v4/actions/{appId}/{definitionId}
Get a specific action definition
PATCH
/automation/v4/actions/{appId}/{definitionId}
Update an action definition
PUT
/automation/v4/actions/{appId}/{definitionId}/functions/{functionType}
Attach a function to an action
POST
/automation/v4/actions/callbacks/{callbackId}/complete
Complete a workflow callback
POST
/automation/v4/actions/callbacks/complete
Batch complete callbacks
GET
/automation/v4/actions/{appId}/{definitionId}/revisions
List action definition revisions
Jentic AI Readiness Score
This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.
A
Automation Actions V4
- Foundational (D)46/100
59
Foundational Compliance63
Developer Experience & Jentic Compatibility23
AI-Readiness & Agent Experience94
Agent Usability52
Security74
AI DiscoverabilityPowered by JenticScoring Framework 1.0.0 | Scoring Engine 0.4.0
Show dimension breakdown
59
Foundational Compliance
Base layer of spec validity and structural soundness.
Grade: C+Signals: 4
88%
Lint Results
Aggregated quality score from linter diagnostics, weighted by severity.
100%
Resolution Completeness
Percentage of `$ref` references that resolve successfully.
0%
Specification Validity
Checks whether the API description parses successfully and conforms to its declared specification (e.g., OpenAPI).
50%
Structural Integrity
Structural correctness score based on schema issues using logarithmic dampening.
63
Developer Experience & Jentic Compatibility
Clarity, completeness, and ingestion readiness for developers and tooling.
Grade: BSignals: 4
3%
Example Density
How richly the API is illustrated with examples.
100%
Example Validity
Percentage of examples that conform to their schemas.
50%
Response Coverage
Percentage of operations with complete response definitions (success, client error, server error).
100%
Tooling Readiness
Health of API ingestion, bundling, and resolution within Jentic pipelines.
23
AI-Readiness & Agent Experience
Semantic breadth, depth, and agent comprehension for AI systems.
Grade: FSignals: 4
28%
Description Coverage
Coverage of descriptions across API elements.
0%
Error Standardization
Coverage of RFC 9457 Problem Details for error responses.
0%
OperationId Quality
Coverage, uniqueness, and casing consistency of operationIds for AI inference.
64%
Summary Coverage
Coverage of summaries across operations/tags/info.
94
Agent Usability
Functional utility, complexity comfort, and AI orchestration readiness.
Grade: A+Signals: 1
94%
Complexity Comfort
Agent comfort level based on API operational and structural complexity.
52
Security
Trust, risk posture, and security compliance.
Grade: C-Signals: 1
52%
Authentication Strength
Average quality of security schemes based on authentication method strength (weakest link for OAuth2).
74
AI Discoverability
Findability, semantic richness, and reasoning readiness.
Grade: A-Signals: 1
74%
Descriptive Richness
Clarity and depth of descriptions across API elements.
Score it yourself
Every API in the directory is allowlisted, so you can re-score it with no key required.
npx @jentic/api-scorecard-cli score <openapi-url>Why Jentic?
What agents get from Jentic-routed access to this vendor.
Setup
Wiring HubSpot Automation Actions V4 by hand means handling both OAuth and app-token auth, tracking app and definition ids across api.hubapi.com, and attaching functions and completing callbacks yourself. Through Jentic you install once, import Automation Actions V4 from the API Directory, store the credential once, and your agent calls it.
Permission scoping
HubSpot puts the app id in the URL path (/automation/v4/actions/{appId}), so a rule can pin your agent to one app: it defines and reads workflow actions for that app and nothing else. You choose the operations it may call, so a function replacement with PUT or a DELETE on a definition is not included unless you add it.
Credential isolation
Your HubSpot credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
Intent-based discovery
Agents search Jentic by intent such as 'create a custom workflow action', and Jentic returns the matching operation under /automation/v4/actions/{appId} with its input schema so the agent calls the right endpoint without browsing the reference docs.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Automation Actions V4 API through Jentic.
What authentication does the HubSpot Automation Actions V4 API use?
The API supports OAuth 2.0 with the 'automation' scope for production apps and developer API keys (hapikey) for testing. OAuth tokens are obtained via HubSpot's authorization flow at https://app.hubspot.com/oauth/authorize. Through Jentic, OAuth tokens and developer keys are stored encrypted in your Jentic One instance with automatic token refresh.
Can I create custom workflow actions with typed input fields?
Yes. POST to /automation/v4/actions/{appId} with a definition body containing inputFields array. Each input field specifies a typeDefinition (string, number, enumeration, etc.), label, and whether it's required. HubSpot users see these fields in the workflow editor when configuring your custom action step.
What are the rate limits for the HubSpot Automation Actions V4 API?
HubSpot enforces standard API rate limits: 100 requests per 10 seconds for OAuth apps and 500,000 requests per day. Batch callback completion at /automation/v4/actions/callbacks/complete processes multiple callbacks in a single request, reducing rate limit consumption for high-volume workflow executions.
How do I complete a workflow callback through Jentic?
Search Jentic for 'complete workflow automation callback' to find the POST /automation/v4/actions/callbacks/{callbackId}/complete operation. Provide the callbackId received when HubSpot invokes your action, along with output field values in the request body. Install with pip install jentic and use the search-load-execute flow.
What function types can I attach to custom actions?
The API supports multiple function types attached via PUT /automation/v4/actions/{appId}/{definitionId}/functions/{functionType}. Function types include PRE_ACTION_EXECUTION for validation before the action runs, POST_ACTION_EXECUTION for the main processing logic, and FETCH_OPTIONS for dynamically populating input field dropdown options in the workflow editor.
Can I version and roll back action definitions?
Yes. Every update to an action definition via PATCH /automation/v4/actions/{appId}/{definitionId} creates a new revision. Retrieve revision history via GET /automation/v4/actions/{appId}/{definitionId}/revisions and inspect any specific revision with GET /automation/v4/actions/{appId}/{definitionId}/revisions/{revisionId}. Active workflows reference specific revisions.
What HubSpot plan is required to use the Automation Actions V4 API?
Custom workflow actions require HubSpot Professional or Enterprise tier across Marketing, Sales, or Service Hubs. The API itself is available to any HubSpot developer app, but end users configuring the actions in workflows need the Professional tier or higher to access the workflow tool.
Can I limit what my agent is allowed to do with the HubSpot Automation Actions V4 API?
Yes. Because Jentic One is self-hosted by you, your own rules decide which operations and credentials the agent may use. HubSpot carries the app id in the URL path (/automation/v4/actions/{appId}), so you can pin the agent to a single app and let it only define and read workflow actions for that app and nothing else. You also choose which operations it may call, so a function replacement with PUT or a DELETE on a definition stays out of reach unless you explicitly grant it.
GET STARTED