Learn how to use the v4 automation API (BETA).
automation
scope. In addition, if you need to access sensitive data properties in a workflow, enroll records in a workflow that references sensitive data, or retrieve enrollment and performance data for workflows with sensitive data properties, you’ll need to authorize sensitive data scopes that are detailed in the sections below.
Learn more about working with sensitive data in the HubSpot Knowledge Base.
crm.objects.contacts.sensitive.read
: view enrollment and performance data for existing contact-based workflows.crm.objects.companies.sensitive.read
: view enrollment and performance data for existing company-based workflows.crm.objects.deals.sensitive.read
: view enrollment and performance data for existing deal-based workflows.crm.objects.custom.sensitive.read
: view enrollment and performance data for workflows based on custom objects an account.crm.objects.contacts.sensitive.write
: create and delete contact-based workflows via the v4 API, as well as enroll contacts in existing workflows that access sensitive data.crm.objects.companies.sensitive.write
: create and delete company-based workflows via the v4 API, as well as enroll companies in existing workflows that access sensitive data.crm.objects.deals.sensitive.write
: create and delete deal-based workflows via the v4 API, as well as enroll deals in existing workflows that access sensitive data.crm.objects.custom.sensitive.write
: create and delete workflows based on custom objects via the v4 API, as well as enroll custom object records in existing workflows that access sensitive data.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:
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"
:
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.
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 a DELAY
action). A full list of actions and their associated actionTypeId
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.), the actionTypeVersion
will be 0
.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 the edgeType
to "GO-TO"
.nextActionId
: the ID of the subsequent action in the workflow.type
: for non-branching actions, this should be set to SINGLE_CONNECTION
.fields
: an object that specifies the data required by the action (e.g., how long to delay an enrolled object for a DELAY
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.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). |
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). |
Add enrolled object to list | 0-63809083 | Add an enrolled contact to a static list. |
Remove enrolled object from list | 0-63863438 | Remove an enrolled contact from a static list. |
fields
property of your action depends on the corresponding action type.
GET
request to /automations/v4/flows/{flowId}
for that workflow. You can find the flowId
of the workflow by editing the workflow then checking the URL for the second ID in the URL path, or you can make a GET
request to /automations/v4/flows
to get all workflows and filter the resulting response by the name of your workflow.date
field accordingly:
STATIC_VALUE
for the type
sub-property, then provide the calendar date for the staticValue
sub-property as a unix timestamp.OBJECT_PROPERTY
for the type
sub-property, then specify the property to use as the propertyName
.113782603056
to an enrolled contact.
hs_lead_status
property to "IN_PROGRESS"
.
listId
.
listId
.
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.
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.
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.
enrollmentCriteria
property of your workflow specification.
type
of enrollmentCriteria
to either EVENT_BASED
or LIST_BASED
.shouldReEnroll
field to true
or false
.eventFilterBranches
. Each eventFilterBranch
definition specifies a qualifying event (e.g., a form submission) using an eventTypeId
that corresponds to that event.operator
: "HAS_COMPLETED"
filterBranchType
: "UNIFIED_EVENTS"
filterBranchOperator
: "AND"
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 |
enrollmentCriteria
to enroll contacts who successfully submitted a form:
listFilterBranch
field of your enrollmentCriteria
based which objects should qualify for enrollment in your workflow. Within a listFilterBranch, you can define the specific filter criteria using a list of filterBranches
.listFilterBranch
in the list filters documentation.enrollmentCriteria
below defines the criteria for when a contact’s City property is equal to Dublin:
POST
request to /automations/v4/flows
and provide a workflow specification in the body of your request.
actions
in your workflow and configuring the enrollmentCriteria
.type
to "CONTACT_FLOW"
. For all other workflow types (e.g., deal-based, goal-based, etc.), set the type
to "PLATFORM_FLOW"
.POST
request would resemble the following:
/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.
revisionId
and type
properties in your request body.revisionId
must correspond to the most current revision of your workflow, which you can retrieve by making a GET
request to /automation/v4/{flowId}
."5"
:
DELETE
request to /automations/v4/{flowId}
using the ID of the workflow you want to delete as the flowId
.