canonical: https://jentic.com/apis/hubspot.com/hubspot-automation-v4

# HubSpot Automation V4

The HubSpot Automation V4 API gives programmatic access to HubSpot workflows. The /automation/v4/flows endpoints list, create, retrieve, update, and delete workflows, and a batch-read endpoint pulls multiple workflows in a single call. /automation/v4/flows/email-campaigns returns the marketing emails attached to workflows so external systems can audit which sends are workflow-driven, and /automation/v4/workflow-id-mappings/batch/read returns mappings between legacy and migrated workflow ids. Authentication uses legacy OAuth or a legacy private app token in the private-app-legacy header.

## For AI agents

Create, read, update, and delete HubSpot workflows, plus pull workflow email campaigns and migrated workflow id mappings.

## Scope

Does not enroll specific contacts, send individual emails, or schedule sales tasks - use only for managing HubSpot workflow definitions and reading their attached marketing emails.

## Capabilities

- Retrieve a paginated list of workflows on a HubSpot portal
- Create a new HubSpot workflow from a JSON definition
- Retrieve the full definition of a workflow by id
- Update a workflow's triggers, actions, or enrolment settings
- Delete a workflow that is no longer needed
- Batch-read multiple workflows by id in one request
- List the marketing emails sent by HubSpot workflows

## Use cases

### Programmatically clone a workflow into a new portal

When provisioning a new HubSpot portal, an integration can copy a baseline set of workflows from a template portal. GET /automation/v4/flows/{flowId} returns the full workflow definition, then POST /automation/v4/flows on the new portal recreates it. The same definition shape works in both directions, so a single export-import job can stand up dozens of workflows.

Example prompt: Call GET /automation/v4/flows/{flowId} on the source portal, then POST /automation/v4/flows on the target portal with the returned definition body

### Audit which marketing emails come from workflows

A marketing ops review wants to know which sends are workflow-driven versus campaign-driven. GET /automation/v4/flows/email-campaigns returns the marketing emails that workflows reference, so the review can separate automated from one-off sends. The endpoint is paginated for portals with hundreds of workflows.

Example prompt: Call GET /automation/v4/flows/email-campaigns, page through results, and join the email ids to the marketing emails report

### Pause a workflow during a release window

Before a product release, an operator can disable a workflow so customers receive no automated touches during the change window. PUT /automation/v4/flows/{flowId} updates the workflow definition with the enrolment switch off, and the same call after the release re-enables it.

Example prompt: Call PUT /automation/v4/flows/{flowId} with isEnabled set to false, then call it again with isEnabled true after the release

### Agent integration via Jentic

An ops agent can stand up a new welcome workflow from a brief in plain English. Through Jentic the agent searches for the workflow creation operation, loads the schema, and executes with the JSON body it generates from the brief. The HubSpot credential never leaves your Jentic One instance.

Example prompt: Search Jentic for 'create a hubspot workflow', load POST /automation/v4/flows, and execute with a definition body that triggers on form submission and sends a welcome email

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /automation/v4/flows | List workflows on the portal |
| POST | /automation/v4/flows | Create a new workflow |
| GET | /automation/v4/flows/{flowId} | Retrieve a workflow by id |
| PUT | /automation/v4/flows/{flowId} | Update a workflow |
| DELETE | /automation/v4/flows/{flowId} | Delete a workflow |
| POST | /automation/v4/flows/batch/read | Batch-read workflows by id |
| GET | /automation/v4/flows/email-campaigns | List marketing emails sent by workflows |
| POST | /automation/v4/workflow-id-mappings/batch/read | Resolve legacy workflow ids to migrated ids |

## Key resources

- **Workflows** — List, create, retrieve, update, and delete HubSpot workflows; batch-read by id
- **Email campaigns** — List the marketing emails referenced by workflows
- **Workflow ID mappings** — Resolve legacy workflow ids to migrated ids

## Why Jentic

- **Setup:** Wiring HubSpot Automation V4 by hand means registering an OAuth app for the authorization-code flow or minting a private app token, targeting api.hubapi.com, and handling paging and rate limits on the flows endpoints yourself. Through Jentic you install once, import Automation V4 from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Automation V4 puts the flow id in the URL path (/automation/v4/flows/{flowId}), so a rule can pin your agent to one workflow: it can read and update that flow and nothing else. You choose the operations it may call, so destructive ones like deleting a flow are not included unless you add them.
- **Credential handling:** Your HubSpot OAuth token or private app token 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.
- **Discovery method:** Agents search Jentic by intent such as 'create a HubSpot workflow' or 'list automation flows', and Jentic returns the matching Automation V4 operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **HubSpot Automation Actions V4** — Define custom workflow actions that the workflows in this API can call
- **HubSpot Automation Sequences** — Sequences are the salesperson-driven equivalent of workflows for one-to-one outreach
- **HubSpot Automation API** — Equivalent automation surface published under the hubapi.com vendor namespace
- **Zapier Natural Language Actions** — Zapier orchestrates HubSpot workflows from outside HubSpot using its own automation engine

## FAQ

### What authentication does the HubSpot Automation V4 API use?

The spec defines two legacy security schemes: OAuth 2.0 (oauth2_legacy) and a legacy private app token sent in the private-app-legacy header. Both can call all eight endpoints. Through Jentic the credential is stored encrypted in the vault.

### Can I create a workflow programmatically with the Automation V4 API?

Yes. POST /automation/v4/flows accepts a workflow definition JSON body that describes the trigger, the action sequence, and the enrolment settings. The response returns the new flowId which you can then update with PUT /automation/v4/flows/{flowId} or delete with DELETE.

### What are the rate limits for the HubSpot Automation V4 API?

The spec does not declare per-endpoint limits. Workflow endpoints share the standard HubSpot per-account limit of around 100 requests per 10 seconds for OAuth and private apps, and bulk import jobs should use the batch-read endpoint to stay under the burst cap.

### How do I list all workflows through Jentic?

Search Jentic for 'list hubspot workflows', load the schema for GET /automation/v4/flows, and execute. Jentic returns the paginated JSON list with each flow's id, name, and isEnabled flag.

### Can I see which marketing emails are sent by workflows?

Yes. GET /automation/v4/flows/email-campaigns returns the marketing emails referenced by workflows on the portal, so a marketing ops review can split automated sends from one-off campaigns.

### Why does the API include a workflow id mapping endpoint?

POST /automation/v4/workflow-id-mappings/batch/read resolves legacy workflow ids to the new id format used by V4. This is useful when migrating an integration that previously stored legacy ids and needs to look them up against current workflows.

### Can I limit what my agent is allowed to do with the HubSpot Automation V4 API?

Yes. Because you self-host Jentic One, your own rules decide which Automation V4 operations and credentials the agent may use. Since the flow id sits in the URL path at /automation/v4/flows/{flowId}, you can pin the agent to a single workflow so it only reads and updates that flow with GET and PUT and touches nothing else. You choose the operations it may call, so a destructive one like DELETE /automation/v4/flows/{flowId} is left out unless you explicitly add it.