Skip to main content

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.

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:

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

FieldTypeDescription
idStringThe sequence ID.
nameStringThe name of the sequence.
stepsArrayThe 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:

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

FieldTypeDescription
totalStringThe number of sequences in your account.
idStringThe sequence ID.
nameStringThe name of the sequence.
createdAtStringThe time the sequence was created in UTC format.
updatedAtStringThe time the sequence was last updated in UTC format.
userIDStringThe 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:

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

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

FieldTypeDescription
idStringThe ID for the enrollment object.
toEmailStringThe email of the contact
enrolledAtStringThe time the contact was enrolled in the sequence in UTC format.
updatedAtStringThe last time the enrollment was updated (paused, unpaused, etc.)

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:

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

FieldTypeDescription
idStringThe ID for the enrollment object.
toEmailStringThe email of the contact
enrolledAtStringThe time the contact was enrolled in the sequence in UTC format.
updatedAtStringThe last time the enrollment was updated (paused, unpaused, etc.)
sequenceIDStringThe ID of the sequence the contact is enrolled in.
sequenceNameStringThe title of the sequence the contact is enrolled in.
enrolledByStringThe userId of the user who enrolled the contact in the sequence.
enrolledByEmailStringThe email of the user who enrolled the contact in the sequence or the email address that email messages are sent from.