Skip to content
Book a build

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.

On this page

What HubSpot supports natively

Detail (October 2026)
APIv4 Automation API, flows endpoints, beta
OperationsCreate (POST), read one or a batch, update (PUT), delete
Scopeautomation; plus crm.objects.*.sensitive scopes if the workflow uses sensitive properties
Workflow typesCONTACT_FLOW for contact-based workflows; PLATFORM_FLOW for deals, tickets, custom objects and the rest
PathsHubSpot 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.
  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 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. 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.

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. 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.

Sources

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

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

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.