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:

POST

Content Type:

application/json

Response Format:

json

Requires Authentication?

Yes

Rate Limited?

Yes

Headers

User-Agent

Products:

Marketing

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:  https://api.hubapi.com/automation/v3/workflows?hapikey=demo

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

About

Jobs

Learn Inbound

Support

Locations

HubSpot, Inc.
25 First Street, 2nd Floor
Cambridge, MA 02141
European Headquarters
Ground Floor, Two Dockland Central
Guild Street, Dublin 1
Asia/Pacific Office
20 Hunter St, Level 7
Sydney NSW 2000
View our other locations
Example POST URL: https://api.hubapi.com/automation/v3/workflows?hapikey=demo You can create a workflow with any of the available workflow actions. When in doubt, create a workflow in HubSpot with the desired actions first and inspect the API response from the workflow request. The body below will create a workflow with an action to set the contact property Company to HubSpot, and then immediately trigger a webhook to the URL shown with the given auth credentials. "Delay" actions are optional and if no delay is desired, it can be left out. Delay values are required to be in milliseconds; this workflow with execute the actions 1 hour after each contact is enrolled. Delays can be added between groups of actions as well. { "name": "Test Workflow", "type": "DRIP_DELAY", "onlyEnrollsManually": true, "actions": [ { "type": "DELAY", "delayMillis": 3600000 }, { "newValue": "HubSpot", "propertyName": "company", "type": "SET_CONTACT_PROPERTY" }, { "type": "WEBHOOK", "url": "https://www.myintegration.com/webhook.php", "method": "POST", "authCreds": { "user": "user", "password": "password" } } ] } Changing the "type" field and setting the "eventAnchor" field lets you create date-based workflows. For example, this workflow is based on a static date of October 9, 2014 for all contacts enrolled and will execute the property action at 12:00pm on that date. { "name": "Test Workflow", "type": "STATIC_ANCHOR", "onlyEnrollsManually": true, "eventAnchor": { "staticDateAnchor": "10/09/2014" }, "actions": [ { "type": "DELAY", "delayMillis": 0, "anchorSetting": { "boundary": "ON", "execTimeOfDay": "12:00 PM" } }, { "type": "SET_CONTACT_PROPERTY", "propertyName": "company", "newValue": "HubSpot" } ] } The workflows above don't have any enrollment criteria, so contacts will only be enrolled manually. To specify enrollment criteria so the workflow automatically enrolls contacts, use the same format as list "filters" described in the Contact Lists API. Put these filters in the workflow's "segmentCriteria" field. For example, this workflow enrolls contacts that have a Lead, SQL or MQL lifecycle stage. { "name": "Test Workflow", "type": "DRIP_DELAY", "segmentCriteria": [ [ { "operator": "SET_ANY", "value": "lead;salesqualifiedlead;marketingqualifiedlead", "property": "lifecyclestage", "type": "string" } ] ], "actions": [ // ... ] } To create a workflow with branching logic, add a branch action as shown below with a group of actions nested within the branch's "acceptActions" and "rejectActions" fields, which correspond to the YES/NO branches, respectively. To specify branch criteria, put the desired list filters in the branch action's "filters" field. You can nest branches up to 15 levels deep in workflows. The body below creates a workflow that sets the HubSpot owner ID to one value or the other based on whether the contact's industry is "Marketing Software." { "name": "Test Workflow", "type": "DRIP_DELAY", "onlyEnrollsManually": true, "actions": [ { "type": "BRANCH", "filters": [ [ { "operator": "EQ", "value": "Marketing Software", "property": "industry", "type": "string" } ] ], "acceptActions": [ { "type": "SET_CONTACT_PROPERTY", "propertyName": "hubspot_owner_id", "newValue": "12345" } ], "rejectActions": [ { "type": "SET_CONTACT_PROPERTY", "propertyName": "hubspot_owner_id", "newValue": "67890" } ] } ] }