There's a new version of the HubSpot API

Check out the new API

As of November 30, 2022, HubSpot API keys are no longer a supported authentication method for accessing HubSpot APIs. Instead, you should use a private app access token or OAuth to authenticate API calls. Learn more about this change and how to migrate an API key integration to use a private app instead.

Create a workflow

Last updated May 15, 2023

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

This endpoint is used to create a new workflow in your portal. Workflows automate your marketing, sales, and service processes and make your team more efficient. Workflows can execute relevant and timely actions, based on specific enrollment triggers. Learn more about how you can create a workflow in your HubSpot account.

Required / Optional Parameters How to use Description
Required OAuth access token or private app access token Authorization: Bearer {token} header Used to authenticate the request. Please see this page for more details about authentication.
Required Workflow JSON Used in the request body This is JSON that represents the workflow that you're creating.
Optional 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.

Key Parameters

Example post URL:  https://api.hubapi.com/automation/v3/workflows

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

Supported Actions

Only certain actions are supported when using this API. Any actions not in the following list will be considered an UNSUPPORTED_ACTION. If an UNSUPPORTED_ACTION is included, the workflow will not be created.

A list supported actions can be found below:

Type Definition
ADD_SUBTRACT_PROPERTY Increase or decrease a value in a number type property for the enrolled contact.
COPY_COMPANY_PROPERTY Copy a property value from the enrolled contact's associated company to another property in the same contact.
COPY_PROPERTY Copy a property value of the enrolled contact to another property in the same record.
CREATE_SFDC_TASK Set a customized Salesforce task for the enrolled contact.
DEAL Create a new deal record. This deal will be associated with the enrolled contact.
EMAIL Send marketing emails that have been saved for automation to the enrolled contact.
LEAD_ASSIGNMENT Assign the enrolled contacts to users equally within a selected team or between specified users. This action is only compatible with activated, paid users.
NOTIFICATION Send internal marketing emails that have been saved for automation to specified email addresses, or a contact property that stores an email address, including any custom properties.
NOTIFICATION_STATION Send an in-app notification to specified teams or users.
SET_COMPANY_PROPERTY Set a property value on the enrolled contact's associated company.
SET_CONTACT_PROPERTY Set a property value on the enrolled contact.
SET_SALESFORCE_CAMPAIGN_MEMBERSHIP Set a Salesforce campaign for the enrolled contact.
SMS_NOTIFICATION Send a text message to a HubSpot user or specified number.
TASK Create a new task. This task will be associated with the enrolled contact.
TICKET Create a new ticket record. This ticket will be associated with the enrolled contact.
UPDATE_EMAIL_SUBSCRIPTION Customize the subscription status of the enrolled contact.
UPDATE_LIST Add or remove contacts from a static list.
WEBHOOK Trigger a webhook to an external application.
WORKFLOW_ENROLLMENT Enroll the contact in another workflow.

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 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" } ] } ] }