Automation v4 API (BETA)

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, click the Endpoints tab at the top of this article.

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:

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.

You can consult the sections below on how actions and enrollment criteria are specified.

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 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.

The table below details the available action types along with the associated actionTypeId:

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 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.

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 the type sub-property, then provide the calendar date for the staticValue sub-property as a unix timestamp.
• To delay until a date-based property of the enrolled record, provide OBJECT_PROPERTY for the type sub-property, then specify the property to use as the propertyName.

The code below specifies an example delay action for a preconfigured amount of time.

The following example action demonstrates how to send an automated marketing email with an ID of 113782603056 to an enrolled contact.

The action definition below provides an example of setting the hs_lead_status property to "IN_PROGRESS".

The action definition below is an example of creating an unassigned task:

The example action below creates a new deal and associates it with the contact enrolled in the workflow:

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".

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.

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.

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 of enrollmentCriteria to either EVENT_BASED or LIST_BASED.
• You can specify the re-enrollment settings for objects enrolled in your workflow by setting the shouldReEnroll field to true or false.

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. Each eventFilterBranch definition specifies a qualifying event (e.g., a form submission) using an eventTypeId 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:

The example code below defines the enrollmentCriteria to enroll contacts who successfully submitted a form:

Workflows with filter-based enrollment will enroll objects when the criteria you configure is met.

• Criteria is configured setting the 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.
• 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:

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 the enrollmentCriteria.
• For contact-based workflows, set the type to "CONTACT_FLOW". For all other workflow types (e.g., deal-based, goal-based, etc.), set the type 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:

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.