To send a series of targeted, timed email templates to nurture contacts over time, you can create a sequence. You can use the sequences tool to automatically create tasks to remind you to follow up with your contacts.
To use this API, the user must have an assigned Sales Hub Professional or Enterprise or Service Hub Professional or Enterprise seat.
With the sequences API, you can:
- Get a list of sequences
- Get a specific sequence
- Enroll a contact in a sequence
- View a contact’s enrollment status
This could be useful if you have an app that maintains a list of contacts and you want to enroll them in a HubSpot sequence. With the sequences API, from your app, you could:
- Get a list of sequences
- Enroll a contact in a sequence
- Review the enrollment status
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 get details about a specific sequence in your account, make a GET
request to /automation/v4/sequences/{sequenceId}?userId={userId}
, where the sequenceId is the ID of an existing sequence in your account.
For example, to get details about a sequence that ID is 123456789
and your user ID is 2222222
, make a GET
request to /automation/v4/sequences/123456789?userId=2222222
. Use the ID of the specific sequence as the sequenceId in the request URL and use your userId as a query parameter.
The response for fetching a sequence would resemble the following:
// Example response for GET request to https://api.hubapi.com/automation/v4/sequences/{sequenceId}?userId={userId}
{
"id": "123456789",
"name": "Melinda's simple call sequence",
"createdAt": "2024-06-26T18:37:01.146Z",
"updatedAt": "2024-06-26T18:37:01.146Z",
"userId": "8698664",
"steps": [
{
"id": "198771535",
"stepOrder": 0,
"delayMillis": 0,
"actionType": "TASK",
"createdAt": "2024-06-26T18:37:01.146Z",
"updatedAt": "2024-06-26T18:37:01.146Z",
"taskPattern": {
"id": "23594004",
"taskType": "CALL",
"taskPriority": "LOW",
"subject": "Call contact to follow up",
"createdAt": "2024-06-26T18:37:01.146Z",
"updatedAt": "2024-06-26T18:37:01.146Z"
}
},
{
"id": "198771536",
"stepOrder": 1,
"delayMillis": 86400000,
"actionType": "TASK",
"createdAt": "2024-06-26T18:37:01.146Z",
"updatedAt": "2024-06-26T18:37:01.146Z",
"taskPattern": {
"id": "23594005",
"taskType": "EMAIL",
"taskPriority": "LOW",
"subject": "Send follow-up email",
"notes": "<p>Send an email to thank them for their time and follow up. Use one of our templates based on the call outcome.</p>",
"createdAt": "2024-06-26T18:37:01.146Z",
"updatedAt": "2024-06-26T18:37:01.146Z"
}
},
{
"id": "198771537",
"stepOrder": 2,
"delayMillis": 0,
"actionType": "FINISH_ENROLLMENT",
"createdAt": "2024-06-26T18:37:01.146Z",
"updatedAt": "2024-06-26T18:37:01.146Z"
}
],
"settings": {
"id": "18167737",
"eligibleFollowUpDays": "BUSINESS_DAYS",
"sellingStrategy": "LEAD_BASED",
"sendWindowStartMinute": 480,
"sendWindowEndMinute": 1080,
"taskReminderMinute": 480,
"individualTaskRemindersEnabled": false,
"createdAt": "2024-06-26T18:37:01.146Z",
"updatedAt": "2024-06-26T18:37:01.146Z"
},
"dependencies": [
{
"id": "15241774",
"createdAt": "2024-06-26T18:37:01.146Z",
"updatedAt": "2024-06-26T18:37:01.146Z",
"dependencyType": "TASK_COMPLETION",
"requiredBySequenceStepId": "198771536",
"reliesOnSequenceStepId": "198771535",
"requiredByStepOrder": 1,
"reliesOnStepOrder": 0
},
{
"id": "15241775",
"createdAt": "2024-06-26T18:37:01.146Z",
"updatedAt": "2024-06-26T18:37:01.146Z",
"dependencyType": "TASK_COMPLETION",
"requiredBySequenceStepId": "198771537",
"reliesOnSequenceStepId": "198771536",
"requiredByStepOrder": 2,
"reliesOnStepOrder": 1
}
]
}
The details of each response field are outlined in the table below:
Field | Type | Description |
---|---|---|
id | String | The sequence ID. |
name | String | The name of the sequence. |
steps | Array | The list of steps in your sequence. Each step is an object that includes details like the type, priority, and creation details. |
To get details about a specific sequence in your account, make a GET
request to /automation/v4/sequences/?limit=#&userId={userId}
. Use the amount of sequences you want returned as the limit in the request URL and use your userID as a query parameter.
For example, to get a list of four sequences and your user ID is 2222222
, make a GET
request to /automation/v4/sequences?limit=4&userId=2222222
.
The response for fetching a list of sequences would resemble the following:
xxxxxxxxxx
//Example response for GET request to https://api.hubapi.com/automation/v4/sequences?limit=4&userId={userId}
{
"total": 7,
"results": [
{
"id": "88180366",
"name": "Melinda's call sequence",
"createdAt": "2023-07-20T15:40:04.364Z",
"updatedAt": "2023-07-20T15:40:04.364Z",
"userId": "2222222"
},
{
"id": "76853632",
"name": "Melinda's Follow-up Sequence",
"createdAt": "2023-01-26T15:38:05.812Z",
"updatedAt": "2023-01-27T16:06:12.562Z",
"userId": "2222222"
},
{
"id": "76897322",
"name": "Melinda's Marketing Pro Demo Sequence",
"createdAt": "2023-01-27T16:42:29.487Z",
"updatedAt": "2023-05-03T14:40:42.507Z",
"userId": "2222222"
},
{
"id": "76849666",
"folderId": "67555200",
"name": "Melinda's Sales Sequence",
"createdAt": "2023-01-26T15:26:56.574Z",
"updatedAt": "2023-05-26T17:16:57.866Z",
"userId": "2222222"
}
],
"paging": {
"next": {
"after": "NA%3D%3D",
"link": "https://api.hubspot.com/automation/v4/sequences/?limit=4&userId=8698664&portalId=6331522&hs_static_app=api-goggles&hs_static_app_version=1.7830&after=NA%3D%3D"
}
}
}
The details of each response field are outlined in the table below:
Field | Type | Description |
---|---|---|
total | String | The number of sequences in your account. |
id | String | The sequence ID. |
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. |
To enroll a contact in a sequence, make a POST
request to /automation/v4/sequences/enrollments/
. Use your user ID as the query parameter. 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 sequence that’s ID is 44444444
, you’d make a POST
request to /automation/v4/sequences/enrollments
.
The body would resemble the following:
xxxxxxxxxx
// Example of request body for POST request
{
"sequenceId": "33333",
"contactId": "44444444",
"senderEmail": "menelson@hubspot.com"
}
The response for enrolling a contact in a sequence would resemble the following:
xxxxxxxxxx
// Example response for POST request to https://api.hubapi.com//automation/v4/sequences/enrollments/
{
"id": "2435404604",
"toEmail": "RachelGreen.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.
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/v4/sequences/enrollments/contact/{contactId}
.
For example, to view the enrollment status of a contact whose contact ID is 33333
, make a GET
request to /automation/v4/sequences/enrollments/contact/33333
. Use the contact ID as the query parameter.
The response for viewing a contact's sequence enrollment status would resemble the following:
xxxxxxxxxx
// Example response for GET request to https://api.hubapi.com/automation/v4/enrollments/contact/{contactId}
{
"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. |