Create a workflow

Last updated June 17, 2020

POST /automation/v3/workflows

Note: The Workflows API currently only supports contact-based workflows.

Method Details

HTTP Methods:


Content Type:


Response Format:


Requires Authentication?


Rate Limited?






Create a new workflow in a portal. Workflows are an essential component of the HubSpot marketing product, allowing marketing automation that relies on triggering relevant and timely actions, based on a user's context.

Required Parameters How to use Description
OAuth Access Token or API Key Authorization: Bearer {token} header
or hapikey={key} query parameter.
Used to authenticate the request. Please see this page for more details about authentication.
Workflow JSON Used in the request body This is JSON that represents the workflow that you're creating.
Optional Parameters How to use Description
Validation errors errors=true - Used in the request URL Causes the API to include validation errors and warnings, if present, within the returned workflow body.

Example URL is here:

A good way to see exactly what email IDs and list IDs you want to reference in your JSON as workflow steps would be to create your workflow manually and copy the JSON of these steps. We have documented some of the key parameters below:

Parameter Definition Value
enabled If the workflow is active or not. true/false
name The name of the workflow string
actions Includes delay, action and branching information See the JSON examples to the right and the HubSpot product for possible actions
onlyEnrollsManually If this workflow should only be triggered manually (either by a user in HubSpot or through the API), set this to true. Note: This should only be set to true if segmentCriteria is empty. true/false
segmentCriteria List filters used as the workflow's enrollment criteria See Contact Lists API for examples
goalCriteria List filters used as the goal criteria See Contact Lists API for examples
type If this workflow is based on enrollment or revoles around a static or dyanic date DRIP_DELAY, STATIC_ANCHOR or PROPERTY_ANCHOR
eventAnchor Contains the staticDateAnchor or contactPropertyAnchor setting, if applicable. staticDateAnchor or contactPropertyAnchor
staticDateAnchor If the workflow type is STATIC_ANCHOR, define the date mm/dd/yyyy
contactPropertyAnchor If the workflow type is PROPERTY_ANCHOR, define the property property name
nurtureTimeRange Use enabled to set it enabled can be false/true
unenrollmentSetting Used for kickout workflows. If none, use type:"None" - if this workflows can kick contacts out of others, list them after excludedWorkflows type and excludedWorkflows
suppressionSetting Use for suppression lists. Use listIds if you want set any listIds
onlyExecOnBizDays A setting indicating whether the workflow can execute on business days only true/false
canEnrollFromSalesforce A setting indicating whether the workflow is available to be seen from the HubSpot embed in Salesforce. true/false
allowContactToTriggerMultipleTimes If the same contact can enter the workflow more than once. true/false
listening Whether contacts should be unenrolled from the workflow if they are no longer a member of any of the lists used as starting conditions. true/false