Workflow actions and enrollment types

Scope requirements

When using the workflows v4 API, you’ll need to set up actions and enrollment triggers for your workflows. The sections below provide an overview of the different action types and enrollment criteria when using the v4 endpoints.

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.

Action types

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

Action type IDs

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

Branches and Go to actions do not have an associated actionTypeId.
For integration actions, you can add the action to your workflow, then make a GET request to /automation/v4/flows/{flowId} to retrieve the actionTypeId.

Note that some actions have the same type ID, such as Delay until a calendar date and Delay until a date property. These actions are split into their own table rows to match how they appear in the workflow action sidebar.

Action	Action type ID	Description
Delay until a calendar date	`0-35`	Delay enrolled records until a specific date. Use this delay when you want an action to execute only on a specific date.
Delay until a date property	`0-35`	Delay enrolled records until a specific date or datetime property. Use this when you want an action to execute based on a specific property.
Delay until an event occurs	`0-29`	Delay enrolled records until a specified event occurs, such as a page visit or form submission.
Delay for a set amount of time	`0-1`	Delay enrolled records for a specific amount of days, hours, or minutes before moving to the next action.
Delay until a day of week	`0-1`	Delay enrolled records until a specific day of the week.
Delay until a specific time of day	`0-1`	Delay enrolled records until a specific time of day.
Go to workflow	`0-15`	Enroll record in another workflow of the same type while remaining in the original.
Enroll in a sequence	`0-46510720`	Automatically enroll contacts in a sequence.
Send Email	`0-4`	Send automated marketing emails to contacts enrolled in the workflow.
Send in-app notification	`0-9`	Send a notification to specified users or teams, appearing in the HubSpot notification center/app.
Send an internal email notification	`0-8`	Send an internal email to selected users or teams, configurable with tokens and rich formatting.
Send internal marketing emails	`0-23`	Send automated emails internally to other HubSpot users in your account.
Send survey	`0-199186210`	Automatically send a custom survey to enrolled contacts. (BETA)
Send WhatsApp message	`0-25085031`	Send WhatsApp messages to opted-in contacts with a valid WhatsApp number.
Send SMS message	`0-40900952`	Send SMS to enrolled or associated contacts.
Unenroll from sequence	`0-4702372`	Automatically unenroll contacts from their current sequence.
Assign conversation owner	`0-44475148`	Change the inbox and ownership assignment for a conversation.
Validate and format phone number	`0-225935194`	Format phone numbers for calling compatibility.
Enrich Record	`0-177946906`	Enrich contacts or companies with additional data.
Edit records	`0-5`	Set, edit, copy, or clear property values for enrolled or associated records.
Create record	`0-14`	Automatically create CRM records, including contacts, companies, deals, tickets, leads, and custom objects.
Create task	`0-3`	Automatically create a new HubSpot task for a record.
Create note	`0-169425243`	Automatically create and associate a note with the enrolled record.
Delete contact	`0-18224765`	Automatically delete enrolled contacts.
Increase or decrease property value	`0-5`	Change a numeric value in a number property by a specified amount.
Manage communication subscriptions	`0-43347357`	Update the subscription status, legal basis, and communication consent for a contact.
Rotate record to owner	`0-11`	Evenly distribute enrolled records (e.g. leads, tickets) to selected users or teams.
Create associations	`0-63189541`	Create new CRM record associations.
Apply association labels	`0-73444249`	Add a label to already-associated CRM records.
Update association labels	`0-61139484`	Replace existing or append new labels to associations.
Remove association labels	`0-61139476`	Clear all current association labels.
Stop tracking intent signals	`0-219161394`	Deactivate ongoing intent signals tracking and enrichment.
Track intent signals	`0-219160146`	Activate intent signal tracking & enrichment.
Data Agent: Custom prompt (BETA)	`0-172351286`	Analyze, summarize, or categorize data via custom AI prompts.
Data Agent: Research (BETA)	`0-216647524`	Generate and extract research data using associated record properties or transcripts.
Data Agent: Fill Smart Property (BETA)	`0-201091202`	Run AI smart-properties and populate the corresponding data.
Summarize record (BETA)	`0-195318603`	Summarize data from records and associations, use the output in emails or further actions.
Infer company value proposition and ICP (BETA)	`0-207702619`	Generate selling profiles, including target persona, value prop, and more.
Enroll in prospecting agent (BETA)	`0-219292676`	Automatically enroll contacts in HubSpot’s AI prospecting agent.
Unenroll in prospecting agent (BETA)	`0-217709844`	Remove contacts from the prospecting agent.
Use a custom LLM (BETA)	`0-218870680`	Connect custom Large Language Models (LLMs) to drive AI-powered workflow actions.
Add to ads audience	`0-30`	Add contacts to a new or existing ads audience (created via workflows).
Add to static list	`0-63809083`	Add records (contacts, companies, deals) to static lists.
Remove from ads audience	`0-30`	Remove records from an ads audience.
Remove from static list	`0-63863438`	Remove records from a static list.
Set marketing contact status	`0-31`	Mark contact as marketing or non-marketing. Changes to non-marketing contacts will only occur on the renewal date.
Send Slack notification	`1-179507819`	Send a Slack message via integrated Slack workspace.
Create an Asana task	`1-100451`	Create an Asana task from HubSpot workflow logic.
Create a Trello Card	`1-2825058`	Create a Trello card from HubSpot workflow logic.
Create Salesforce task	`0-19`	Creates a Salesforce task tied to the enrolled contact for Salesforce users.
Set Salesforce campaign	`0-18`	Associate contacts with a Salesforce campaign (contact-based workflows only).

Action fields

The fields property of your action depends on the corresponding action type.

The actions available depend on your account’s subscriptions. Learn more about the available actions in workflows.
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 /automation/v4/flows/{flowId} for that workflow.

The sections below outline the required fields for common actions in a workflow.

In the example code blocks below, note that the nextActionId field values are demonstrative, and should contain the ID of the next action in your particular workflow.

Delay until a specific date or date-based property

The code below specifies a Delay until a calendar date action, but can also be used with a Delay until a date property action. 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.

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

Delay a set amount of time

The code below specifies a Delay for a set amount of time action.

{
  "type": "SINGLE_CONNECTION",
  "actionId": "5",
  "actionTypeVersion": 0,
  "actionTypeId": "0-35",
  "connection": {
    "edgeType": "STANDARD",
    "nextActionId": "7"
  },
  "fields": {
    "delta": "720",
    "time_unit": "MINUTES"
  }
}

Send an automated marketing email to an enrolled contact

The action definition below sends an automated marketing email with an ID of 12345678 to an enrolled contact.

{
  "type": "SINGLE_CONNECTION",
  "actionId": "4",
  "actionTypeVersion": 0,
  "actionTypeId": "0-4",
  "connection": {
    "edgeType": "STANDARD",
    "nextActionId": "10"
  },
  "fields": {
    "content_id": "12345678"
  }
}

Set property

The action definition below sets the hs_lead_status property to "IN_PROGRESS".

{
  "type": "SINGLE_CONNECTION",
  "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"
    }
  }
}

Create task

The action definition below creates an 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"
  }
}

Create a new record

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

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

Add an enrolled object to a static list

The action definition below adds an enrolled contact to a static list, specified as the listId.

{
  "actionId": "3",
  "actionTypeVersion": 0,
  "actionTypeId": "0-63809083",
  "fields": {
    "listId": "123"
  },
  "type": "SINGLE_CONNECTION"
}

Remove an enrolled object from a static list

The action definition below removes an enrolled contact from a static list, specified as the listId.

{
  "actionId": "3",
  "actionTypeVersion": 0,
  "actionTypeId": "0-63863438",
  "fields": {
    "listId": "123"
  },
  "type": "SINGLE_CONNECTION"
}

Branching actions

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

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.

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

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.

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

Enrollment criteria

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

Event-based enrollment

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 Segment membership change event enrollment trigger does not have an associated eventTypeId. Instead, it uses IN_LIST / NOT_IN_LIST operators to determine segment membership.

Event	ID	Description
Ad interaction	`4-1553675`	Triggers when an ad is interacted with.
Call ended	`4-1741072`	Triggers when a call has ended. This includes both calls initiated through HubSpot or through third-party integrations, such as Aircall.
Call started	`4-1733817`	Triggers when a call is initiated. This includes both calls initiated through HubSpot or through third-party integrations, such as Aircall.
CRM Object created	`4-1463224`	Triggers when a new object is created in the CRM. You must use refinement criteria to filter out unwanted objects from enrollment.
Playbook log	`4-1814177`	Triggers when a playbook is logged on a record in the CRM.
Property value changed	`4-655002`	Triggers when a property value is updated on a record in the CRM. This trigger represents exactly one property changing from one value to another.
Custom event occurs	`6-2117363`	Triggers when a custom event occurs with an existing contact record. Custom events triggers will only enroll existing records.
Clicked link in email	`4-666288`	Triggers when a contact clicks a link in a marketing email. When further defining your email event enrollment triggers, both Raw URL and Original URL criteria will include any query parameters added by the user and tracking parameters added by HubSpot.
Email bounced	`4-5470331`	Triggers when a one-to-one or marketing email is sent to a contact and bounces.
Email delivered	`4-665536`	Triggers when a one-to-one or marketing email is delivered to a contact.
Email sent	`4-667638`	Triggers when a marketing email, or one-to-one email, is sent to a contact. This event will only trigger for one-to-one emails if sent through a hosted inbox.
Opened email	`4-666440`	Triggers when a contact opens a marketing email.
Replied to email	`4-665538`	Triggers when a contact replies to a marketing email.
Updated email subscription status	`4-666289`	Triggers when a contact updates their email subscription status.
Form interaction	`4-1639799`	Triggers when a contact interacts with a form field. This event fires before form submission.
Form submission	`4-1639801`	Triggers when a form is submitted.
Form view	`4-1639797`	Triggers when a contact views a form. Will only trigger for visitors that are associated with existing contact records.
Meeting booked	`4-1720599`	Triggers when a contact books a meeting through the HubSpot meetings tool or when a meeting activity is associated with the contact.
Meeting outcome change	`4-1724222`	Triggers when a meeting outcome is changed in the account.
Contact finished viewing a document	`4-1522438`	Triggers when a contact has finished viewing a sales document. This occurs when the user completes the view by clicking out of the document.
Contact viewed a document	`4-1522436`	Triggers when a contact views a sales document. This represents the initial view of a document, regardless of whether the contact finished viewing it.
Document shared with contact	`4-1522437`	Triggers when a sales document is shared with a contact.
Contact booked a meeting through a sequence	`4-675773`	Triggers when a contact books a meeting through a sequence.
Contact enrolled in a sequence	`4-675777`	Triggers when a contact is enrolled in a sequence.
Contact finished sequence	`4-675778`	Triggers when a contact finishes a sequence.
Contact unenrolled from sequence	`4-675776`	Triggers when a contact is unenrolled from a sequence.
Contact unenrolled from sequence via workflow	`4-1497402`	Triggers when a contact is unenrolled from a sequence via a workflow. Other unenrollment sources do not trigger this event.
Contact unenrolled from sequence manually	`4-675775`	Triggers when a contact is manually unenrolled from a sequence. Other unenrollment sources do not trigger this event.
Delivering SMS failed	`4-1752910`	Triggers when an SMS message wasn’t delivered to a contact.
Link in SMS clicked	`4-1722276`	Triggers when a contact clicks a link in an SMS message.
Sending SMS failed	`4-1752904`	Triggers when an SMS message wasn’t sent to a contact.
SMS delivered	`4-1721168`	Triggers when an SMS message is delivered to a contact.
SMS dropped	`4-1725149`	Triggers when a SMS message is dropped for a contact.
SMS sent	`4-1719453`	Triggers when an SMS message is sent to a contact.
CTA click	`4-1555805`	Triggers when a contact clicks a CTA or Web interactive.
CTA viewed	`4-1555804`	Triggers when a contact views a CTA or Web interactive.
CTA click (legacy)	`4-100216`	Triggers when a contact clicks a CTA (legacy).
CTA view (legacy)	`4-100215`	Triggers when a contact views a CTA (legacy).
Page visited	`4-96000`	Triggers when a contact views a landing page or website page. Will only trigger for visitors that are associated with existing contact records.
Website or Email Media Play	`4-675783`	Triggers when a contact plays a media file embedded in your content (e.g., on a website page, email, etc.)
Achieved workflow goal	`4-1753168`	Triggers when a contact meets a workflow goal.
Enrolled in workflow	`4-1466013`	Triggers when an object is enrolled in a workflow.
Unenrolled from workflow	`4-1466014`	Triggers when an object is unenrolled from a workflow.

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

"enrollmentCriteria": {
  "shouldReEnroll": true,
  "type": "EVENT_BASED",
  "eventFilterBranches": [
    {
      "filterBranches": [],
      "filters": [],
      "eventTypeId": "4-1639801",
      "operator": "HAS_COMPLETED",
      "filterBranchType": "UNIFIED_EVENTS",
      "filterBranchOperator": "AND"
    }
  ],
  "listMembershipFilterBranches": []
}

Filter-based enrollment

Workflows with filter-based enrollment will enroll records when the configured criteria is met.

The criteria is configured by setting the listFilterBranch field of your enrollmentCriteria, based on which objects should qualify for enrollment in your workflow. Within a listFilterBranch, you can define the specific filter criteria using a list of filterBranches.
Learn more about the syntax and formatting for defining a listFilterBranch.

For example, the enrollmentCriteria below defines the criteria for when a contact’s 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": []
}

​Action types

​Action type IDs

​Action fields

​Delay until a specific date or date-based property

​Delay a set amount of time

​Send an automated marketing email to an enrolled contact

​Set property

​Create task

​Create a new record

​Add an enrolled object to a static list

​Remove an enrolled object from a static list

​Branching actions

​List branch actions

​Static branch actions

​Enrollment criteria

​Event-based enrollment

​Filter-based enrollment

Action types

Action type IDs

Action fields

Delay until a specific date or date-based property

Delay a set amount of time

Send an automated marketing email to an enrolled contact

Set property

Create task

Create a new record

Add an enrolled object to a static list

Remove an enrolled object from a static list

Branching actions

List branch actions

Static branch actions

Enrollment criteria

Event-based enrollment

Filter-based enrollment