---
title: "Create a workflow with the HubSpot API (v4, beta)"
description: "How to create a workflow with the HubSpot API: the beta v4 flows endpoint, the automation scope, contact vs platform flows, and how updates and deletes behave."
url: "https://jetstack.ai/answers/create-workflow-hubspot-api/"
---

# How do I create a workflow with the HubSpot API?

To create a workflow with the HubSpot API, POST a workflow definition to the flows endpoint of the v4 Automation API, which is still in beta. The definition includes the type (CONTACT_FLOW or PLATFORM_FLOW), object type, actions, enrollment criteria and isEnabled. Your credential needs the automation scope. Updates replace the whole workflow and need the current revisionId; deletes are permanent.

![](https://jetstack.ai/images/authors/aditya-kumar.webp)

By [Aditya Kumar](https://jetstack.ai/authors/aditya-kumar/) Founder, Jetstack AI

Updated October 30, 2026

On this page

## What HubSpot supports natively

|                | Detail (October 2026)                                                                                                                                                      |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| API            | v4 Automation API, flows endpoints, **beta**                                                                                                                               |
| Operations     | Create (`POST`), read one or a batch, update (`PUT`), delete                                                                                                               |
| Scope          | `automation`; plus `crm.objects.*.sensitive` scopes if the workflow uses sensitive properties                                                                              |
| Workflow types | `CONTACT_FLOW` for contact-based workflows; `PLATFORM_FLOW` for deals, tickets, custom objects and the rest                                                                |
| Paths          | HubSpot publishes date-versioned beta paths (for example `/automation/v4/2027-03-beta/flows` in its current reference); copy the path from the reference you build against |

A create body includes `type`, `objectTypeId`, `isEnabled`, the `actions` list and `enrollmentCriteria`, and the reference schema lists further fields such as `timeWindows`, `blockedDates` and `dataSources`. HubSpot documents action and enrollment types in a separate reference.

## How to create a workflow with the HubSpot API

1. **Build a model workflow in HubSpot** that’s close to what you want, and GET it. Copying working action JSON is far more reliable than writing it from the schema.
2. **Collect what the definition references in the target portal.** Properties are referenced by internal name (for example `hs_lead_status`), so check each one exists there with the same internal name and option values. List, email, form, owner, pipeline and stage IDs are portal-specific and never carry over between portals.
3. **Create dependencies first.** Properties, lists and emails the workflow references must exist before you POST it. See [creating a property with the API](https://jetstack.ai/answers/create-property-hubspot-api).
4. **POST with `isEnabled: false`.** Review the workflow in HubSpot, including enrollment and re-enrollment settings.
5. **Test with one record**, then turn it on.

## How updates and deletes behave

- **Updates are full replacements.** A `PUT` must include the current `revisionId` and `type`, and anything from the earlier GET you leave out is removed. Omit an action and it’s deleted.
- **Stale revisions fail.** If someone edits the workflow in HubSpot between your GET and PUT, fetch again.
- **Deletes are permanent** through the API; restoring needs HubSpot Support.

If you’re scripting this with an AI coding tool, see [building HubSpot workflows with Claude Code](https://jetstack.ai/answers/build-hubspot-workflows-claude-code) for guardrails. To build new workflows without writing the definitions, IDs and ordering yourself, we recommend Jetstack AI Projects.

## Where Jetstack AI fits

For a new workflow, use [Projects](https://jetstack.ai/build). Describe the trigger, branches and actions in a brief; Jetty, the Projects assistant, turns it into a plan you approve, builds the properties and lists it depends on first, and deploys only after a separate approval. The workflow is created switched off, and the receipt confirms what HubSpot saved by reading it back. Projects is currently in limited release; see the [quickstart](https://jetstack.ai/docs/projects/quickstart).

When the workflow already exists somewhere, Jetstack’s CLI and API import it from the source portal with its dependencies, show what needs mapping in the target, and deploy it with the mapping you provide; see the [CLI quick start](https://jetstack.ai/docs/developers/cli). You can roll back a Portal reuse deployment: Jetstack shows you what will be removed first, then deletes the assets that deployment created in the destination portal. It won’t delete anything another deployment or Project still uses, and it skips assets that were changed after the deployment. Details are in the [developer overview](https://jetstack.ai/docs/developers).

## Sources

- [Workflows API guide, beta (HubSpot Developers)](https://developers.hubspot.com/docs/api-reference/2027-03-beta/automation/workflows/guide)
- [Create a workflow, beta (HubSpot API reference)](https://developers.hubspot.com/docs/api-reference/2027-03-beta/automation/workflows/create-workflow)
- [Workflow action and enrollment reference, beta (HubSpot Developers)](https://developers.hubspot.com/docs/api-reference/2027-03-beta/automation/workflows/action-enrollment-reference)
- [CLI (Jetstack AI documentation)](https://jetstack.ai/docs/developers/cli)

Checked October 30, 2026. HubSpot changes its products often; tell us at <team@jetstack.ai> if something here is out of date.

![Aditya Kumar](https://jetstack.ai/images/authors/aditya-kumar.webp)

About the author

[Aditya Kumar](https://jetstack.ai/authors/aditya-kumar/)

Founder, Jetstack AI

Aditya Kumar is the founder of Jetstack AI, the AI platform HubSpot partners and RevOps teams use to audit portals, build implementations and reuse their best setups across portals. He writes about HubSpot architecture, automation and AI from the work of building it.

[More from Aditya](https://jetstack.ai/authors/aditya-kumar/) [LinkedIn](https://www.linkedin.com/in/aditya-ambrstack/)

API & developers

## Do it from your own code or AI agent.

The Jetstack AI REST API, MCP server and CLI share API keys and scopes. Create and manage those keys in the app.

[Read the developer docs](https://jetstack.ai/docs/developers)

On this page

API & developers

## Related questions.

How do I create a workflow with the HubSpot API?

To create a workflow with the HubSpot API, POST a workflow definition to the flows endpoint of the v4 Automation API, which is still in beta. The definition includes the type (CONTACT_FLOW or PLATFORM_FLOW), object type, actions, enrollment criteria and isEnabled. Your credential needs the automation scope. Updates replace the whole workflow and need the current revisionId; deletes are permanent.

Is the HubSpot workflows API production-ready?

HubSpot labels it beta and says it's subject to change, with use governed by its Developer Beta Terms. Many teams use it, but pin the version you build against and re-test when HubSpot publishes a new one.

Can I copy a workflow to another portal with the API?

You can GET it from one portal and POST it to another. Properties are referenced by internal name, so the copy works only if every property it uses exists in the target with the same internal name and option values. Lists, emails, forms, owners and pipeline stages are referenced by portal-specific IDs, and without remapping those the copy points at nothing.

Can I restore a workflow I deleted through the API?

Not through the API. HubSpot says deletion is permanent there and restoring needs HubSpot Support.
