You can use the automation v4 API to fetch data from existing workflows, create new workflows, as well as delete workflows you no longer need.
The sections below provide a walkthrough of how to use the v4 endpoints. For a full reference of the available endpoints and their required fields, check out the endpoint reference documentation.
Please note: This API is currently in beta and is subject to change based on testing and feedback. By using these endpoints you agree to adhere to HubSpot's Developer Terms& Developer Beta Terms. You also acknowledge and understand the risk associated with testing an unstable API.
The sections below detail how to fetch details about specific workflows, or getting details about multiple workflows in a single call.
To fetch data from an existing workflow, make a GET
request to /automation/v4/flows/{flowId}
, where flowId
is the ID an existing workflow in your account.
For example, if you made a GET
request to /automation/v4/flows/585051946
to get the workflow with an ID of 585051946
, the resulting response would be:
// Example workflow response from GET request to /automations/v4/flows/585051946
{
"id": "585051946",
"isEnabled": true,
"flowType": "WORKFLOW",
"revisionId": "7",
"name": "New form submission workflow",
"createdAt": "2024-06-07T17:27:08.101Z",
"updatedAt": "2024-06-07T17:31:11.263Z",
"startActionId": "1",
"nextAvailableActionId": "3",
"actions": [
{
"type": "SINGLE_CONNECTION",
"actionId": "1",
"actionTypeVersion": 0,
"actionTypeId": "0-13",
"connection": {
"edgeType": "STANDARD",
"nextActionId": "2"
},
"fields": {
"operation": "ADD",
"list_id": "178"
}
},
{
"type": "SINGLE_CONNECTION",
"actionId": "2",
"actionTypeVersion": 0,
"actionTypeId": "0-9",
"fields": {
"user_ids": ["2620022"],
"delivery_method": "APP",
"subject": "New form submission",
"body": "Check out the new form submission we received!"
}
}
],
"enrollmentCriteria": {
"shouldReEnroll": false,
"type": "EVENT_BASED",
"eventFilterBranches": [
{
"filterBranches": [],
"filters": [],
"eventTypeId": "4-1639801",
"operator": "HAS_COMPLETED",
"filterBranchType": "UNIFIED_EVENTS",
"filterBranchOperator": "AND"
}
],
"listMembershipFilterBranches": []
},
"timeWindows": [],
"blockedDates": [],
"customProperties": {},
"crmObjectCreationStatus": "COMPLETE",
"type": "CONTACT_FLOW",
"objectTypeId": "0-1",
"suppressionListIds": [],
"canEnrollFromSalesforce": false
}
The response above includes the specification for a contact-based workflow with two actions, and contacts are enrolled if they filled out a form on your website.
To fetch multiple workflows using their IDs, you can make a POST
request to the /automation/v4/flows/batch/read
endpoint, and provide the ID of each workflow as the flowId
, along with a type
of "FLOW_ID"
within an inputs
array provided in the request body.
For example, the request body below would fetch the workflow details for two workflows with IDs of "619727002"
and "617969780"
:
xxxxxxxxxx
// Example request body for POST request to /automation/v4/flows/batch/read
{
"inputs": [
{
"flowId": "619727002",
"type": "FLOW_ID"
},
{
"flowId": "617969780",
"type": "FLOW_ID"
}
]
}
To fetch all workflows, you can make a GET
request to /automation/v4/flows
. Keep in mind that the response will only include key fields for the workflow, such as id
, isEnabled
, objectTypeId
, and the latest revisionId
.
If you want to get a full list of properties for a specific workflow, make a GET
request to /automation/v4/flows/{flowId}
and provide the specific ID of the workflow as the flowId
.
You can consult the sections below on how actions
and enrollmentCriteria for a workflow are specified. Once you review these specifications, you can follow the steps in the Create a workflow section to define and create a workflow using the v4 API.
Each workflow specification consists of a list of actions. Each action contains a set of required properties:
actionId
: a unique ID that identifies this action, provided as a string.actionTypeId
: a predefined value that specifies the action type (e.g.,"0-1"
designates aDELAY
action). A full list of actions and their associatedactionTypeId
is provided in the section below.actionTypeVersion
: a number that designates the version of the action. For all built-in action types (e.g., a delay, email notification, etc.), theactionTypeVersion
will be0
.connection
: for non-branching actions, this property is an object that specifies the subsequent action, and contains two nested properties:edgeType
: to proceed directly to the next action, this property should be set to"STANDARD"
. If you have a branch in your workflow, you can go to an action in a different branch by setting theedgeType
to"GO-TO"
.nextActionId
: the ID of the subsequent action in the workflow.
type
: for non-branching actions, this should be set toSINGLE_CONNECTION
.fields
: an object that specifies the data required by the action (e.g., how long to delay an enrolled object for aDELAY
action). The structure of this property depends on the action type. Consult the sections and example actions below for the fields each action type expects.
The table below details the available action types along with the associated actionTypeId
:
Action | Action type ID | Description |
---|---|---|
Delay until a specific date or date-based property | 0-35 | Delay until a preconfigured calendar date or date property of the enrolled record. |
Delay a set amount of time, until a specific day of the week, or time of day. | 0-1 | Delay for a preconfigured amount of time (e.g., 3 hours, 5 days, etc.), until a specific day (e.g., Tuesday), or time of day (12:00 AM EST). |
Add enrolled object to list or remove from list | 0-13 | Add or remove an enrolled contact to/from a static list. |
Send automated email to a contact associated with the enrolled record | 0-4 | Send an automated marketing email to the enrolled record. |
Send email notification to a user or team | 0-8 | Send an internal email notification to a user or team in your account. |
Send an in-app notification to a user or team | 0-9 | Trigger an in-app notification to a user or team in your account. |
Set property | 0-5 | Set a property on an enrolled object. |
Create task | 0-3 | Create a new task. |
Create a new record | 0-14 | Create a new record (contact, company, deal, ticket, or lead). |
The fields
property of your action depends on the corresponding action type.
- The actions available depend on your account subscription. Learn about all available actions in this knowledge base article.
- To confirm the fields required for a specific action, you can create the workflow with that action using the workflows tool, then make a
GET
request to/automations/v4/flows/{flowId}
for that workflow. You can find theflowId
of the workflow by editing the workflow then checking the URL for the second ID in the URL path, or you can make aGET
request to/automations/v4/flows
to get all workflows and filter the resulting response by the name of your workflow.
The sections below outline the required fields for common actions in a workflow.
The code below specifies an example delay action until a specific date. Based on whether you're delaying until a preconfigured date or a date-based property of the enrolled record, you'll need to specify the sub-properties of the date
field accordingly:
- If you're delaying until a specific calendar date, provide
STATIC_VALUE
for thetype
sub-property, then provide the calendar date for thestaticValue
sub-property as a unix timestamp. - To delay until a date-based property of the enrolled record, provide
OBJECT_PROPERTY
for thetype
sub-property, then specify the property to use as thepropertyName
.
xxxxxxxxxx
// Example of a delay action to delay until a specific date or date-based property
{
"type": "SINGLE_CONNECTION",
"actionId": "5",
"actionTypeVersion": 0,
"actionTypeId": "0-35",
"connection": {
"edgeType": "STANDARD",
"nextActionId": "7"
},
"fields": {
"date": {
"type": "STATIC_VALUE",
"staticValue": "1719446400000"
},
"delta": "0",
"time_unit": "DAYS",
"time_of_day": {
"hour": 12,
"minute": 0
}
}
}
The code below specifies an example delay action for a preconfigured amount of time.
xxxxxxxxxx
// Example of a delay action to delay for a specific amount of time (e.g., 6 hours)
{
"type": "SINGLE_CONNECTION",
"actionId": "5",
"actionTypeVersion": 0,
"actionTypeId": "0-35",
"connection": {
"edgeType": "STANDARD",
"nextActionId": "7"
},
"fields": {
"delta": "720",
"time_unit": "MINUTES"
}
}
The following example action demonstrates how to send an automated marketing email with an ID of 113782603056
to an enrolled contact.
xxxxxxxxxx
// Example action to send an automated marketing email to an enrolled contact
{
"type": "SINGLE_CONNECTION",
"actionId": "4",
"actionTypeVersion": 0,
"actionTypeId": "0-4",
"fields": {
"content_id": "113782603056"
}
}
The action definition below provides an example of setting the hs_lead_status
property to "IN_PROGRESS"
.
xxxxxxxxxx
// Example action to set the hs_lead_status property to IN_PROGRESS
{
"actionId": "2",
"actionTypeVersion": 0,
"actionTypeId": "0-5",
"connection": {
"edgeType": "STANDARD",
"nextActionId": "4"
},
"fields": {
"property_name": "hs_lead_status",
"association": {
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 1
},
"value": {
"staticValue": "IN_PROGRESS"
}
}
}
The action definition below is an example of creating an unassigned task:
xxxxxxxxxx
// Example action definition for creating a new unassigned task
{
"type": "SINGLE_CONNECTION",
"actionId": "1",
"actionTypeVersion": 0,
"actionTypeId": "0-3",
"fields": {
"task_type": "TODO",
"subject": "Check in with lead",
"body": "<p>Remember to sync up with new lead!</p>",
"associations": [
{
"target": {
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 10
},
"value": {
"type": "ENROLLED_OBJECT"
}
}
],
"use_explicit_associations": "true",
"priority": "NONE"
}
}
The example action below creates a new deal and associates it with the contact enrolled in the workflow:
xxxxxxxxxx
// Example action definition for creating a new deal and associating it with the enrolled contact
{
"type": "SINGLE_CONNECTION",
"actionId": "2",
"actionTypeVersion": 0,
"actionTypeId": "0-14",
"connection": {
"edgeType": "STANDARD",
"nextActionId": "3"
},
"fields": {
"object_type_id": "0-3",
"properties": [
{
"targetProperty": "dealstage",
"value": {
"type": "STATIC_VALUE",
"staticValue": "appointmentscheduled"
}
},
{
"targetProperty": "dealname",
"value": {
"type": "STATIC_VALUE",
"staticValue": "New deal"
}
},
{
"targetProperty": "amount",
"value": {
"type": "STATIC_VALUE",
"staticValue": "1000"
}
}
],
"associations": [
{
"target": {
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 3
},
"value": {
"type": "ENROLLED_OBJECT"
}
}
],
"use_explicit_associations": "true"
}
}
The following action definition is an example of adding an enrolled contact to a static list, specified as the list_id
. To remove an enrolled object from a list, switch the operation
property to "REMOVE"
.
xxxxxxxxxx
// Example action to add an enrolled contact to a list
{
"type": "SINGLE_CONNECTION",
"actionId": "4",
"actionTypeVersion": 0,
"actionTypeId": "0-13",
"fields": {
"operation": "ADD",
"list_id": "178"
}
}
Branching actions differ from other actions in that they don't follow the standard action structure. Branching action definitions don't have fields
or connection
properties. There are two types of branching actions: list branch actions and static branch actions. Both types must also define a default branch using the defaultBranchName
and defaultBranch
properties.
List branch actions include a listBranches
property that specifies a set of filter branches to segment enrolled objects. Each filterBranch
is configured using the syntax and formatting outlined in the list filters documentation.
xxxxxxxxxx
// Example list branch action
{
"actionId": "6",
"listBranches": [
{
"filterBranch": {},
"connection": {
"edgeType": "STANDARD",
"nextActionId": "7"
}
},
{
"filterBranch": {},
"branchName": "Some branch name",
"connection": {
"edgeType": "GOTO",
"nextActionId": "4"
}
}
],
"defaultBranchName": "Fall-through branch",
"defaultBranch": {
"edgeType": "STANDARD",
"nextActionId": "8"
}
}
Static branch actions include an inputValue
definition, which supports different shapes for the input values of the branch. It also includes a list of staticBranches
, which defines which actions come next in the branch.
xxxxxxxxxx
// Example static branch action
{
"actionId": "1",
"inputValue": {
"propertyName": "example_property"
},
"staticBranches": [
{
"branchValue": "example_value_1",
"connection": {
"edgeType": "STANDARD",
"nextActionId": "2"
}
},
{
"branchValue": "example_value_1",
"connection": {
"edgeType": "STANDARD",
"nextActionId": "3"
}
}
// ...
],
"defaultBranchName": "Fall-through branch",
"defaultBranch": {
"edgeType": "STANDARD",
"nextActionId": "4"
}
}
You can configure the conditions for objects to be enrolled in your workflow within the enrollmentCriteria
property of your workflow specification.
- The data you specify varies based on whether your enrollment is event-based or list-based. You can specify the enrollment type by setting the
type
ofenrollmentCriteria
to eitherEVENT_BASED
orLIST_BASED
. - You can specify the re-enrollment settings for objects enrolled in your workflow by setting the
shouldReEnroll
field totrue
orfalse
.
Learn more about workflow enrollment in this knowledge base article.
Event-based workflows will enroll objects when specific events occur, such as when a form is submitted.
- You can configure the criteria for which events will trigger enrollment by defining a list of
eventFilterBranches
. EacheventFilterBranch
definition specifies a qualifying event (e.g., a form submission) using aneventTypeId
that corresponds to that event. - Most events will have the same values for the following fields:
operator
:"HAS_COMPLETED"
filterBranchType
:"UNIFIED_EVENTS"
filterBranchOperator
:"AND"
The table below defines each eventTypeId
that corresponds to the event you can configure for your workflow:
Event | Event type ID |
---|---|
Ad interaction | 4-1553675 |
Email open | 4-666440 |
Email reply | 4-665538 |
Email click | 4-666288 |
Email delivery | 4-665536 |
Form submission | 4-1639801 |
Form view | 4-1639797 |
Form interaction | 4-1639799 |
Marketing event registration | 4-68559 |
Marketing event cancellation | 4-69072 |
Call start | 4-1733817 |
Call end | 4-1741072 |
SMS shortlink click | 4-1722276 |
CTA view | 4-1555804 |
CTA click | 4-1555805 |
Media play on webpage | 4-675783 |
The example code below defines the enrollmentCriteria
to enroll contacts who successfully submitted a form:
xxxxxxxxxx
// Example of an enrollmentCriteria definition to enroll contacts who submitted a form
"enrollmentCriteria": {
"shouldReEnroll": true,
"type": "EVENT_BASED",
"eventFilterBranches": [
{
"filterBranches": [],
"filters": [],
"eventTypeId": "4-1639801",
"operator": "HAS_COMPLETED",
"filterBranchType": "UNIFIED_EVENTS",
"filterBranchOperator": "AND"
}
],
"listMembershipFilterBranches": []
}
Workflows with filter-based enrollment will enroll objects when the criteria you configure is met.
- Criteria is configured setting the
listFilterBranch
field of yourenrollmentCriteria
based which objects should qualify for enrollment in your workflow. Within a listFilterBranch, you can define the specific filter criteria using a list offilterBranches
. - You can learn more about the syntax and formatting for defining a
listFilterBranch
in the list filters documentation.
For example, the enrollmentCriteria
below defines the criteria for when a contact's City property is equal to Dublin:
xxxxxxxxxx
// Example of an enrollmentCriteria definition to filter contacts based on whether their city property is equal to 'Dublin'
"enrollmentCriteria": {
"shouldReEnroll": false,
"type": "LIST_BASED",
"listFilterBranch": {
"filterBranches": [
{
"filterBranches": [],
"filters": [
{
"property": "city",
"operation": {
"operator": "IS_EQUAL_TO",
"includeObjectsWithNoValueSet": false,
"values": [
"Dublin"
],
"operationType": "MULTISTRING"
},
"filterType": "PROPERTY"
}
],
"filterBranchType": "AND",
"filterBranchOperator": "AND"
}
],
"filters": [],
"filterBranchType": "OR",
"filterBranchOperator": "OR"
},
"unEnrollObjectsNotMeetingCriteria": false,
"reEnrollmentTriggersFilterBranches": []
}
To create a workflow, make a POST
request to /automations/v4/flows
and provide a workflow specification in the body of your request.
- Consult the Action types and Enrollment criteria sections above for a full reference on specifying the
actions
in your workflow and configuring theenrollmentCriteria
. - For contact-based workflows, set the
type
to"CONTACT_FLOW"
. For all other workflow types (e.g., deal-based, goal-based, etc.), set thetype
to"PLATFORM_FLOW"
.
For example, if you wanted to create a workflow that executed the following:
- Once a contact submits a specific form on your website, a ticket will be created in your account.
- After a 1 day delay, the enrolled contact will be sent an automated marketing email.
The request body of your POST
request would resemble the following:
xxxxxxxxxx
// Example request body for POST request to create a workflow
{
"isEnabled": true,
"flowType": "WORKFLOW",
"name": "New form submission from interested contact",
"startActionId": "1",
"nextAvailableActionId": "4",
"actions": [
{
"type": "SINGLE_CONNECTION",
"actionId": "1",
"actionTypeVersion": 0,
"actionTypeId": "0-14",
"connection": {
"edgeType": "STANDARD",
"nextActionId": "3"
},
"fields": {
"object_type_id": "0-5",
"properties": [
{
"targetProperty": "subject",
"value": {
"type": "STATIC_VALUE",
"staticValue": "Review new form submission"
}
},
{
"targetProperty": "hs_pipeline_stage",
"value": {
"type": "STATIC_VALUE",
"staticValue": "1"
}
},
{
"targetProperty": "source_type",
"value": {
"type": "STATIC_VALUE",
"staticValue": "FORM"
}
},
{
"targetProperty": "content",
"value": {
"type": "STATIC_VALUE",
"staticValue": "[Triage required] new form submitted. Next available rep should review."
}
}
],
"associations": [
{
"target": {
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 16
},
"value": {
"type": "ENROLLED_OBJECT"
}
},
{
"target": {
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 339
},
"value": {
"type": "COPY_ASSOCIATION",
"sourceSpec": {
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 279
}
}
}
],
"use_explicit_associations": "true"
}
},
{
"type": "SINGLE_CONNECTION",
"actionId": "2",
"actionTypeVersion": 0,
"actionTypeId": "0-4",
"fields": {
"content_id": "113782603056"
}
},
{
"type": "SINGLE_CONNECTION",
"actionId": "3",
"actionTypeVersion": 0,
"actionTypeId": "0-1",
"connection": {
"edgeType": "STANDARD",
"nextActionId": "2"
},
"fields": {
"delta": "1440",
"time_unit": "MINUTES"
}
}
],
"enrollmentCriteria": {
"shouldReEnroll": false,
"type": "EVENT_BASED",
"eventFilterBranches": [
{
"filterBranches": [],
"filters": [
{
"property": "hs_form_id",
"operation": {
"operator": "IS_ANY_OF",
"includeObjectsWithNoValueSet": false,
"values": ["2f5cc7f8-d359-4e9c-a770-dd42ea07d217"],
"operationType": "ENUMERATION"
},
"filterType": "PROPERTY"
}
],
"eventTypeId": "4-1639801",
"operator": "HAS_COMPLETED",
"filterBranchType": "UNIFIED_EVENTS",
"filterBranchOperator": "AND"
}
],
"listMembershipFilterBranches": []
},
"timeWindows": [],
"blockedDates": [],
"customProperties": {},
"crmObjectCreationStatus": "COMPLETE",
"type": "CONTACT_FLOW",
"objectTypeId": "0-1",
"suppressionListIds": [],
"canEnrollFromSalesforce": false
}
To update an existing workflow, make a PUT request to /automation/v4/{flowId}
using the ID of your workflow you want to update as the flowId, and providing any properties you want to change in the request body.
- You must include the
revisionId
andtype
properties in your request body. - The
revisionId
must correspond to the most current revision of your workflow, which you can retrieve by making aGET
request to/automation/v4/{flowId}
.
For the example, to enable a workflow that's currently turned off, the request body below would enable the workflow, using its most recent revisionId of "5"
:
xxxxxxxxxx
// Example request body for PUT request to update a workflow
{
"isEnabled": true,
"revisionId": "5",
"type": "CONTACT_FLOW"
}
To delete a workflow, make a DELETE
request to /automations/v4/{flowId}
using the ID of the workflow you want to delete as the flowId
.
Please note: once deleted, you cannot restore the workflow via the automation API. You must contact HubSpot Support to get assistance with restoring your workflow.