There's a new version of the HubSpot 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.