Older answers say workflows are UI-only
Older answers, our own notes from earlier this year among them, say workflows can be read through the API but only built in the workflow builder. HighLevel's changelog now documents a Workflows API that writes them too. HighLevel has changed this before, so check the current docs before you plan a build around either answer.
The catch is the word beta. An announced API isn't access on every location. If your requests come back with a 403 and WORKFLOW_API_NOT_ENABLED_FOR_LOCATION, the rest of your setup can be right and the location still lacks beta access. The changelog's answer to that error is to request access.
The docs tell you a route exists. A call from your own location tells you whether you have it.
How the Workflows API behaves
Every request carries Version: v3 and a locationId. The scopes split the work up: View Workflows, Edit Workflows, Publish Workflows, Delete Workflows and View Workflow Logs.
- Creating a workflow gives you a draft. Nothing runs until it's published.
- An update replaces the complete definition. Whatever you leave out of the update is gone.
- Editing a workflow that's already published means putting it in draft mode, pausing contacts and turning off its triggers first.
- Deleting a workflow is permanent, and contacts enrolled in it stop.
Changing a live workflow safely
Because an update overwrites the whole definition, the safe pattern is read, change, check, then write. Publishing is its own step, and it should come after a planned pause, not straight after the edit.
- Read the current definition and keep a copy of it.
- Make your change to that full copy, not to a fragment.
- Validate the new definition before you send it.
- Put the workflow in draft, pause its contacts and turn off its triggers.
- Send the update, then publish as a separate call.
- Check the workflow logs to confirm it's running the way you meant.
Creating a pipeline
Pipelines have a documented create route: POST /opportunities/pipelines, with a name, the stages and the locationId. It needs a sub-account token with the pipelines.create scope and Version: v3, and the pipeline must have at least one stage.
Two naming rules trip people up. A pipeline name has to be unique within the location, and the check ignores case, so Sales and sales clash. Stage names have to be unique inside their own pipeline.
Rather have it set up for you?
We'll check what each of your locations can reach, build what the API supports and finish the rest in the workflow builder, after a 30-minute 1:1 with Rob to plan it.
Before you plan a build around the API
Find out what each of your locations can actually reach before you promise anything to a client. Pipelines through the documented route are the straightforward part. Workflows depend on beta access per location, so a build that works in one sub-account can return the not-enabled error in the next.
Where the API can't reach, the workflow builder still can. We plan builds so the parts that need the builder are known up front, rather than found halfway through.