Sequences API - HubSpot docs

Supported products

Required Scopes

Use sequences to send a series of targeted, timed email templates to nurture contacts over time. You can use the sequences tool to automatically create tasks to remind you to follow up with your contacts. Contacts can automatically unenroll from a sequence when they reply to an email or book a meeting. With the sequences API, you can:

Create a sequence
Retrieve a specific sequence
Update a sequence
Delete a sequence
Get a list of sequences
Enroll a contact in a sequence
Review the enrollment status

For example, use these API endpoints with an external application that maintains a list of contacts, to enroll those contacts in a HubSpot sequence. To use this API, the user must have an assigned Sales Hub or Service Hub Professional or Enterprise seat.

Show steps for retrieving sequenceId or userId

When using the Sequences API, you may need to retrieve a sequenceId or userId to populate the API request.

To retrieve the sequenceId, you can either:
- Refer to the URL of the sequence. For example, in the URL https://app.hubspot.com/sequences/123456/sequence/555555, the sequenceId will be 555555.
- Make a GET request to /automation/sequences/2026-09-beta?limit=#&userId={userId} to retrieve sequences by a specific user.
To retrieve the userId, you can either:
- Refer to the user’s internal name in the Internal User ID user property
- Make a GET request to /crm/objects/2026-03/users to retrieve all users.

Scope requirements

The following scopes are required to use the Sequences API, based on the endpoints you’re using:

automation.sequences.read: grants access to view details about sequences and their associated assets. This scope is required for all endpoints.
automation.sequences.enrollments.write: grants access to create, delete, and modify sequence enrollments. This is required for all modification endpoints.

Create a sequence

To create a new sequence, send a POST request to /automation/sequences/2026-09-beta/serviceaccounts/sequences.

Create a new sequence

{
 "name": "Example Sequence",
 "folderId": "123456",
 "dynamic": true,
 "settings": {
   "eligibleFollowUpDays": "EVERYDAY",
   "useThreadedFollowUps": true,
   "sellingStrategy": "LEAD_BASED",
   "sendWindowStartMinute": 0,
   "sendWindowEndMinute": 0,
   "taskCreationMinute": 0,
   "taskReminderMinute": 0,
   "individualTaskRemindersEnabled": true,
   "unenrollmentSettings": {
     "emailSettings": {
       "criteria": "ALL",
       "sellingStrategy": "LEAD_BASED"
     },
     "meetingSettings": {
       "criteria": "ALL",
       "sellingStrategy": "LEAD_BASED"
     }
   }
 },
 "engagementTriggers": {
   "numberOfOpens": 0,
   "numberOfClicks": 0
 },
 "steps": [
   {
     "stepOrder": 0,
     "delayMillis": 0,
     "delayMillisMin": 0,
     "delayMillisMax": 0,
     "actionType": "EMAIL",
     "branchNumber": 0,
     "dynamic": true,
     "emailPattern": {
       "templateId": "string",
       "threadEmailToStepOrder": 0
     },
     "taskPattern": {
       "taskType": "CALL",
       "taskPriority": "NONE",
       "subject": "string",
       "notes": "string",
       "queueId": "string",
       "templateId": "string",
       "threadEmailToStepOrder": 0
     },
     "variants": [
       {
         "variantOrdinal": 0,
         "activated": true,
         "emailPattern": {
           "templateId": "string",
           "threadEmailToStepOrder": 0
         },
         "taskPattern": {
           "taskType": "CALL",
           "taskPriority": "NONE",
           "subject": "string",
           "notes": "string",
           "queueId": "string",
           "templateId": "string",
           "threadEmailToStepOrder": 0
         }
       }
     ]
   }
 ],
 "dependencies": [
   {
     "dependencyType": "TASK_COMPLETION",
     "requiredByStepOrder": 0,
     "reliesOnStepOrder": 0,
     "branchNumber": 0
   }
 ]
}

Field	Type	Description
`name`	String	The name of the sequence.
`folderId`	String	The ID of the folder that your sequence will be created in.
`settings`	Object	The settings for your sequence . Learn how to set up your settings.
`steps`	Array	The list of steps in your sequence. Each step is an object that includes details like the type, priority, and creation details. Learn how to set up your steps.
`dependencies`	Array	The dependencies between sequence steps. Learn how to set up your dependencies.

Retrieve a sequence

To retrieve an existing sequence, send a GET request to /automation/sequences/2026-09-beta/serviceaccounts/sequences/{sequenceId}. For example, if your sequenceId is 555555, make a GET request to /automation/sequences/2026-09-beta/serviceaccounts/sequences/555555. The details of each response are as follows:

Please note:If you’ve enrolled into the Sequences unenrollment configuration beta, when retrieving a specific sequence, the "sellingStrategy": "LEAD_BASED" value may not actually match the sequence. This is expected behavior.

Retrieve a sequence response

{
 "id": "555555",
 "name": "Product or Demo Request",
 "createdAt": "2026-07-23T16:52:43.978Z",
 "updatedAt": "2026-07-23T16:52:43.978Z",
 "userId": "123456",
 "steps": [
   {
     "id": "352532039",
     "stepOrder": 0,
     "delayMillis": 0,
     "actionType": "EMAIL",
     "createdAt": "2026-07-23T16:52:43.978Z",
     "updatedAt": "2026-07-23T16:52:43.978Z",
     "emailPattern": {
       "id": "18029100",
       "templateId": "99045721",
       "createdAt": "2026-07-23T16:52:43.978Z",
       "updatedAt": "2026-07-23T16:52:43.978Z"
     }
   },
   {
     "id": "352532040",
     "stepOrder": 1,
     "delayMillis": 86400000,
     "actionType": "TASK",
     "createdAt": "2026-07-23T16:52:43.978Z",
     "updatedAt": "2026-07-23T16:52:43.978Z",
     "taskPattern": {
       "id": "11607205",
       "taskType": "CALL",
       "taskPriority": "HIGH",
       "subject": "Call contact to follow up for product/demo request",
       "notes": "<ul><li>Contact submitted a product/demo request</li><li>First email sent yesterday</li><li>Follow-up with a call</li><li>If no answer leave voicemail</li></ul>",
       "createdAt": "2026-07-23T16:52:43.978Z",
       "updatedAt": "2026-07-23T16:52:43.978Z"
     }
   },
   {
     "id": "352532041",
     "stepOrder": 2,
     "delayMillis": 0,
     "actionType": "TASK",
     "createdAt": "2026-07-23T16:52:43.978Z",
     "updatedAt": "2026-07-23T16:52:43.978Z",
     "taskPattern": {
       "id": "11607206",
       "taskType": "EMAIL",
       "taskPriority": "NONE",
       "subject": "Send follow-up email",
       "createdAt": "2026-07-23T16:52:43.978Z",
       "updatedAt": "2026-07-23T16:52:43.978Z",
       "threadEmailToStepOrder": 0
     }
   },
   {
     "id": "352532042",
     "stepOrder": 3,
     "delayMillis": 259200000,
     "actionType": "EMAIL",
     "createdAt": "2026-07-23T16:52:43.978Z",
     "updatedAt": "2026-07-23T16:52:43.978Z",
     "emailPattern": {
       "id": "18029101",
       "templateId": "99045720",
       "createdAt": "2026-07-23T16:52:43.978Z",
       "updatedAt": "2026-07-23T16:52:43.978Z",
       "threadEmailToStepOrder": 2
     }
   },
   {
     "id": "352532043",
     "stepOrder": 4,
     "delayMillis": 432000000,
     "actionType": "TASK",
     "createdAt": "2026-07-23T16:52:43.978Z",
     "updatedAt": "2026-07-23T16:52:43.978Z",
     "taskPattern": {
       "id": "11607207",
       "taskType": "TODO",
       "taskPriority": "NONE",
       "subject": "Contact completed sequence without a response",
       "createdAt": "2026-07-23T16:52:43.978Z",
       "updatedAt": "2026-07-23T16:52:43.978Z"
     }
   },
   {
     "id": "352532044",
     "stepOrder": 5,
     "delayMillis": 0,
     "actionType": "FINISH_ENROLLMENT",
     "createdAt": "2026-07-23T16:52:43.978Z",
     "updatedAt": "2026-07-23T16:52:43.978Z"
   }
 ],
 "settings": {
   "id": "15272665",
   "eligibleFollowUpDays": "BUSINESS_DAYS",
   "sellingStrategy": "LEAD_BASED",
   "sendWindowStartMinute": 480,
   "sendWindowEndMinute": 1080,
   "taskReminderMinute": 480,
   "individualTaskRemindersEnabled": false,
   "createdAt": "2026-07-23T16:52:43.978Z",
   "updatedAt": "2026-07-23T16:52:43.978Z"
 },
 "dependencies": [
   {
     "id": "4156739",
     "createdAt": "2026-07-23T16:52:43.978Z",
     "updatedAt": "2026-07-23T16:52:43.978Z",
     "dependencyType": "TASK_COMPLETION",
     "requiredBySequenceStepId": "352532041",
     "reliesOnSequenceStepId": "352532040",
     "requiredByStepOrder": 2,
     "reliesOnStepOrder": 1
   },
   {
     "id": "4156740",
     "createdAt": "2026-07-23T16:52:43.978Z",
     "updatedAt": "2026-07-23T16:52:43.978Z",
     "dependencyType": "TASK_COMPLETION",
     "requiredBySequenceStepId": "352532042",
     "reliesOnSequenceStepId": "352532041",
     "requiredByStepOrder": 3,
     "reliesOnStepOrder": 2
   },
   {
     "id": "4156741",
     "createdAt": "2026-07-23T16:52:43.978Z",
     "updatedAt": "2026-07-23T16:52:43.978Z",
     "dependencyType": "TASK_COMPLETION",
     "requiredBySequenceStepId": "352532044",
     "reliesOnSequenceStepId": "352532043",
     "requiredByStepOrder": 5,
     "reliesOnStepOrder": 4
   }
 ]
}

Field	Type	Description
`id`	String	The sequence ID.
`name`	String	The name of the sequence.
`folderId`	String	The identifier of the folder containing the sequence.
`settings`	Object	The settings for your sequence. Learn more about your sequence settings.
`steps`	Array	The list of steps in your sequence. Each step is an object that includes details like the type, priority, and creation details. Learn more about sequence steps.
`dependencies`	Array	The dependencies between sequence steps. Learn more about sequence dependencies.

Retrieve a list of sequences

To retrieve all sequences in your account, make a GET request to /automation/sequences/2026-09-beta/serviceaccounts/sequences. The response for fetching a list of sequences would resemble the following:

Retrieve a list of sequences response

{
  "total": 2,
  "results": [
    {
      "id": "0123456",
      "folderId": "1234567",
      "name": "Joy's call sequence",
      "createdAt": "2026-07-20T15:40:04.364Z",
      "updatedAt": "2026-07-20T15:40:04.364Z",
      "userId": "555555"
    },
    {
      "id": "654321",
      "folderId": "765432",
      "name": "Joy's follow-up sequence",
      "createdAt": "2026-07-20T15:40:04.364Z",
      "updatedAt": "2026-07-20T15:40:04.364Z",
      "userId": "555555"
    }
  ],
  "paging": {
    "next": {
      "after": "string",
      "link": "string"
    },
    "prev": {
      "before": "string",
      "link": "string"
    }
  }
}

The details of each response field are outlined in the table below:

Field	Type	Description
`total`	Integer	The number of sequences in your account.
`id`	String	The sequence ID.
`folderId`	String	The identifier of the folder containing the sequence.
`name`	String	The name of the sequence.
`createdAt`	String	The time the sequence was created in UTC format.
`updatedAt`	String	The time the sequence was last updated in UTC format.
`userId`	String	The userId of the user who created the sequence.

Update a sequence

To update an existing sequence, send a PUT request to /automation/sequences/2026-09-beta/serviceaccounts/sequences/{sequenceId}. For example, if your sequenceId is 555555, make a PUT request to /automation/sequences/2026-09-beta/serviceaccounts/sequences/555555.

When making a PUT request, you must include all fields for the sequence. Any fields not populated will be updated to default values.
When using this endpoint, it’s recommended to make a GET request to /automation/sequences/2026-09-beta/serviceaccounts/sequences/{sequenceId} to retrieve the complete sequence definition first.

Update a sequence

{
 "name": "string",
 "folderId": "string",
 "dynamic": true,
 "settings": {
   "eligibleFollowUpDays": "EVERYDAY",
   "useThreadedFollowUps": true,
   "sellingStrategy": "LEAD_BASED",
   "sendWindowStartMinute": 0,
   "sendWindowEndMinute": 0,
   "taskCreationMinute": 0,
   "taskReminderMinute": 0,
   "individualTaskRemindersEnabled": true,
   "unenrollmentSettings": {
     "emailSettings": {
       "criteria": "ALL",
       "sellingStrategy": "LEAD_BASED"
     },
     "meetingSettings": {
       "criteria": "ALL",
       "sellingStrategy": "LEAD_BASED"
     }
   }
 },
 "engagementTriggers": {
   "numberOfOpens": 0,
   "numberOfClicks": 0
 },
 "steps": [
   {
     "stepOrder": 0,
     "delayMillis": 0,
     "delayMillisMin": 0,
     "delayMillisMax": 0,
     "actionType": "EMAIL",
     "branchNumber": 0,
     "dynamic": true,
     "emailPattern": {
       "templateId": "string",
       "threadEmailToStepOrder": 0
     },
     "taskPattern": {
       "taskType": "CALL",
       "taskPriority": "NONE",
       "subject": "string",
       "notes": "string",
       "queueId": "string",
       "templateId": "string",
       "threadEmailToStepOrder": 0
     },
     "variants": [
       {
         "variantOrdinal": 0,
         "activated": true,
         "emailPattern": {
           "templateId": "string",
           "threadEmailToStepOrder": 0
         },
         "taskPattern": {
           "taskType": "CALL",
           "taskPriority": "NONE",
           "subject": "string",
           "notes": "string",
           "queueId": "string",
           "templateId": "string",
           "threadEmailToStepOrder": 0
         }
       }
     ]
   }
 ],
 "dependencies": [
   {
     "dependencyType": "TASK_COMPLETION",
     "requiredByStepOrder": 0,
     "reliesOnStepOrder": 0,
     "branchNumber": 0
   }
 ]
}

Delete a sequence

To delete a sequence, send a DELETE request to /automation/sequences/2026-09-beta/serviceaccounts/sequences/{sequenceId}. After a sequence is successfully deleted, you’ll receive a 200 OK success code.

Sequence enrollment

Enroll a contact in a sequence

To enroll a contact in a sequence, make a POST request to /automation/sequences/2026-09-beta/enrollments. Use your user ID in your request. Specify the sequenceId, contactId, and senderEmail in the body. The senderEmail must be an email address that’s connected to your HubSpot account. For example, to enroll a contact whose ID is 33333 in a sequence with an ID of 44444444, you’d make a POST request to /automation/sequences/2026-09-beta/enrollments. The body would resemble the following:

{
  "sequenceId": "44444444",
  "contactId": "33333",
  "senderEmail": "menelson@hubspot.com"
}

The response for enrolling a contact in a sequence would resemble the following:

{
  "id": "2435404604",
  "toEmail": "RachelGreen123@hubspot.com",
  "enrolledAt": "2024-06-27T20:11:02.824Z",
  "updatedAt": "2024-06-27T20:11:02.824Z"
}

The details of each response field are outlined in the table below:

Field	Type	Description
`id`	String	The ID for the enrollment object.
`toEmail`	String	The email of the contact.
`enrolledAt`	String	The time the contact was enrolled in the sequence in UTC format.
`updatedAt`	String	The last time the enrollment was updated (paused, unpaused, etc.).

Please note:There is a limit of 1000 enrollments per portal inbox per day.

View a contact’s sequence enrollment status

A contact’s enrollment status will indicate if the contact is enrolled in any sequences at the time of the request. To get a contact’s enrollment status, make a GET request to /automation/sequences/2026-09-beta/enrollments/contact/{contactId}. For example, to view the enrollment status of a contact whose contact ID is 33333, make a GET request to /automation/sequences/2026-09-beta/enrollments/contact/33333. The response for viewing a contact’s sequence enrollment status would resemble the following:

{
  "id": "2435404604",
  "toEmail": "RachelGreen@gmail.com",
  "enrolledAt": "2024-06-27T20:11:02.824Z",
  "updatedAt": "2024-06-27T20:11:02.824Z",
  "sequenceId": "76853632",
  "sequenceName": "Melinda's Sales Hub Sequence",
  "enrolledBy": "8698664",
  "enrolledByEmail": "menelson@hubspot.com"
}

The details of each response field are outlined in the table below:

Field	Type	Description
`id`	String	The ID for the enrollment object.
`toEmail`	String	The email of the contact.
`enrolledAt`	String	The time the contact was enrolled in the sequence in UTC format.
`updatedAt`	String	The last time the enrollment was updated (paused, unpaused, etc.).
`sequenceId`	String	The ID of the sequence the contact is enrolled in.
`sequenceName`	String	The title of the sequence the contact is enrolled in.
`enrolledBy`	String	The userId of the user who enrolled the contact in the sequence.
`enrolledByEmail`	String	The email of the user who enrolled the contact in the sequence or the email address that email messages are sent from.

Sequences API fields

When using the Sequence API, you may use the following fields in your requests or receive the following fields in responses:

Field	Type	Description
`id`	String	The sequence ID.
`name`	String	The name of the sequence.
`folderId`	String	The identifier of the folder containing the sequence.
`settings`	Object	The settings for your sequence. Learn more about sequence settings.
`steps`	Array	The list of steps in your sequence. Each step is an object that includes details like the type, priority, and creation details. Learn more about sequence steps.
`dependencies`	Array	The dependencies between sequence steps. Learn more about dependencies.

Settings

Field	Type	Description
`eligibleFollowUpDays`	string	Days on which follow-up actions are allowed. Accepted values: `BUSINESS_DAYS`, `EVERYDAY`, `WEEKDAYS_ONLY`.
`useThreadedFollowUps`	boolean	Indicates whether follow-up emails should be threaded.
`sellingStrategy`	string	Unenrollment strategy. Accepted values: `ACCOUNT_BASED`, `LEAD_BASED`.
`sendWindowStartMinute`	integer	Start minute of the time window during which automated emails can be sent.
`sendWindowEndMinute`	integer	End minute of the time window during which automated emails can be sent.
`taskReminderMinute`	integer	Minute of day at which task reminders are triggered.
`individualTaskRemindersEnabled`	boolean	Indicates whether individual task reminders are turned on.
`taskCreationMinute`	integer	Indicates the minute at which tasks should be created.
`unenrollmentSettings`	object	Defines the settings for unenrollment.

Dependencies

Field	Type	Description
`dependencyType`	string	Type of dependency between sequence steps. Accepted values: `ADAPTIVE_COMPLETION`, `MANUAL_PAUSE`, `TASK_COMPLETION`.
`requiredByStepOrder`	integer	The order number of the step that requires this dependency.
`reliesOnStepOrder`	integer	The order number of the step responsible for creating and resolving this dependency.

Steps

Field	Type	Description
`stepOrder`	integer	The order of the step within the sequence.
`delayMillis`	integer	Delay in milliseconds before the step is executed.
`actionType`	string	Type of action for the step. Accepted values: `ADAPTIVE_CONTAINER`, `EMAIL`, `FINISH_ENROLLMENT`, `TASK`.
`emailPattern`	object	Email pattern associated with the step. Learn more about email patterns.
`taskPattern`	object	Task pattern associated with the step. Learn more about tasks.

Emails

Field	Type	Description
`templateId`	string	The unique identifier of the email template associated with the pattern.
`threadEmailToStepOrder`	integer	The order identifying the previous step to which the email thread is linked.

Tasks

Field	Type	Description
`taskType`	string	The type of task. Accepted values: `CALL`, `EMAIL`, `LINKED_IN_CONNECT`, `LINKED_IN_MESSAGE`, `MEETING`, `TODO`.
`taskPriority`	string	Priority level of the task. Accepted values: `HIGH`, `LOW`, `MEDIUM`, `NONE`.
`subject`	string	The subject line of the task.
`notes`	string	Additional notes associated with the task.
`queueId`	string	The identifier for the queue associated with the task.
`templateId`	string	The identifier for the template used in the task.
`threadEmailToStepOrder`	integer	The order of the step to which the email thread is related.

​Scope requirements

​Create a sequence

​Retrieve a sequence

​Retrieve a list of sequences

​Update a sequence

​Delete a sequence

​Sequence enrollment

​Enroll a contact in a sequence

​View a contact’s sequence enrollment status

​Sequences API fields

​Settings

​Dependencies

​Steps

​Emails

​Tasks

Scope requirements

Create a sequence

Retrieve a sequence

Retrieve a list of sequences

Update a sequence

Delete a sequence

Sequence enrollment

Enroll a contact in a sequence

View a contact’s sequence enrollment status

Sequences API fields

Settings

Dependencies

Steps

Emails

Tasks