Sequences API - HubSpot docs

Scope requirements

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 sequences endpoints. For a full reference of the available endpoints and their required fields, click the Endpoints tab at the top of this article.

Fetch a sequence

To get details about a specific sequence in your account, make a GET request to /automation/sequences/2026-03/{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/sequences/2026-03/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:

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.

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

List sequences

To get details about a specific sequence in your account, make a GET request to /automation/sequences/2026-03?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/sequences/2026-03?limit=4&userId=2222222. The response for fetching a list of sequences would resemble the following:

{
  "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/sequences/2026-03?limit=4&userId=8698664&portalId=6331522&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.

Enroll a contact in a sequence

To enroll a contact in a sequence, make a POST request to /automation/sequences/2026-03/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/sequences/2026-03/enrollments. The body would resemble the following:

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

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

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

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-03/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-03/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:

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

​Fetch a sequence

​List sequences

​Enroll a contact in a sequence

​View a contact’s sequence enrollment status

Fetch a sequence

List sequences

Enroll a contact in a sequence

View a contact’s sequence enrollment status