> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

---
id: cb8cd3b2-f943-4c8d-b658-bc06b0f2eeca
---

# Sequences API

> Learn how to use the v4 automation API for sequences.

export const PostmanCard = ({title, collectionId}) => {
  return <div className="card-condensed-cta">
      <Card title={title ? title : "Postman collection"} href={`https://app.getpostman.com/run-collection/${collectionId}`} horizontal={true} cta="Run in Postman" icon={<svg xmlns="http://www.w3.org/2000/svg" width={25} height={25} preserveAspectRatio="xMidYMid" viewBox="0 0 256 256">
              <path fill="#FF6C37" d="M254.953 144.253c8.959-70.131-40.569-134.248-110.572-143.206C74.378-7.912 10.005 41.616 1.047 111.619c-8.959 70.003 40.569 134.248 110.572 143.334 70.131 8.959 134.248-40.569 143.334-110.7Z" />
              <path fill="#FFF" d="m174.2 82.184-54.007 54.007-15.229-15.23c53.11-53.11 58.358-48.503 69.236-38.777Z" />
              <path fill="#FF6C37" d="M120.193 137.47c-.384 0-.64-.128-.895-.384l-15.358-15.229a1.237 1.237 0 0 1 0-1.792c54.007-54.006 59.638-48.887 71.028-38.649.255.256.383.512.383.896s-.128.64-.383.896l-54.007 53.878c-.128.256-.512.384-.768.384Zm-13.437-16.509 13.437 13.438 52.087-52.087c-9.47-8.446-15.87-11.006-65.524 38.65Z" />
              <path fill="#FFF" d="m135.679 151.676-14.718-14.718 54.007-54.006c14.46 14.59-7.167 38.265-39.29 68.724Z" />
              <path fill="#FF6C37" d="M135.679 152.956c-.384 0-.64-.128-.896-.384l-14.718-14.718c-.256-.256-.256-.512-.256-.896s.128-.64.384-.895L174.2 82.056a1.237 1.237 0 0 1 1.791 0 15.58 15.58 0 0 1 4.991 11.902c-.256 14.206-16.38 32.25-44.28 58.614-.383.256-.767.384-1.023.384Zm-12.926-15.998c8.19 8.319 11.646 11.646 12.926 12.926 21.5-20.476 42.36-41.464 42.488-55.926.128-3.327-1.152-6.655-3.327-9.214l-52.087 52.214Z" />
              <path fill="#FFF" d="m105.22 121.345 10.878 10.878c.256.256.256.512 0 .768-.128.128-.128.128-.256.128l-22.524 4.863c-1.152.128-2.175-.64-2.431-1.791-.128-.64.128-1.28.512-1.664l13.053-13.054c.256-.256.64-.384.768-.128Z" />
              <path fill="#FF6C37" d="M92.934 139.262c-1.92 0-3.327-1.536-3.327-3.455 0-.896.384-1.792 1.024-2.432l13.053-13.054c.768-.64 1.792-.64 2.56 0l10.878 10.878c.768.64.768 1.792 0 2.56-.256.256-.512.384-.896.512l-22.524 4.863c-.256 0-.512.128-.768.128Zm11.902-16.51-12.542 12.543c-.256.256-.383.64-.128 1.024.128.383.512.511.896.383l21.116-4.607-9.342-9.342Z" />
              <path fill="#FFF" d="M202.739 52.238c-8.191-7.935-21.373-7.679-29.307.64-7.935 8.318-7.679 21.372.64 29.306A20.678 20.678 0 0 0 199.155 85l-14.59-14.59 18.174-18.172Z" />
              <path fill="#FF6C37" d="M188.405 89.223c-12.158 0-22.012-9.854-22.012-22.012 0-12.158 9.854-22.012 22.012-22.012 5.631 0 11.134 2.176 15.23 6.143.255.256.383.512.383.896s-.128.64-.384.895L186.357 70.41l13.566 13.566c.512.512.512 1.28 0 1.792l-.256.256c-3.327 2.047-7.295 3.199-11.262 3.199Zm0-41.337c-10.75 0-19.452 8.703-19.324 19.453 0 10.75 8.702 19.452 19.452 19.324 2.944 0 5.887-.64 8.575-2.047l-13.438-13.31c-.256-.256-.384-.512-.384-.896s.128-.64.384-.895l17.149-17.15c-3.456-2.943-7.807-4.479-12.414-4.479Z" />
              <path fill="#FFF" d="m203.122 52.622-.255-.256-18.301 18.044 14.461 14.462c1.408-.896 2.816-1.92 3.967-3.072a20.51 20.51 0 0 0 .128-29.178Z" />
              <path fill="#FF6C37" d="M199.155 86.28c-.384 0-.64-.128-.896-.384l-14.589-14.59c-.256-.256-.384-.512-.384-.896s.128-.64.384-.895l18.173-18.173a1.237 1.237 0 0 1 1.791 0l.384.256c8.575 8.574 8.575 22.396.128 31.098-1.28 1.28-2.687 2.432-4.223 3.328-.384.128-.64.256-.768.256Zm-12.798-15.87 12.926 12.926c1.024-.64 2.048-1.536 2.816-2.304 7.294-7.294 7.678-19.196.64-26.875L186.357 70.41Z" />
              <path fill="#FFF" d="M176.375 84.488a7.879 7.879 0 0 0-11.134 0l-48.247 48.247 8.063 8.063 51.062-44.792c3.328-2.816 3.584-7.807.768-11.134-.256-.128-.384-.256-.512-.384Z" />
              <path fill="#FF6C37" d="M124.929 142.077c-.384 0-.64-.128-.896-.383l-8.063-8.063a1.237 1.237 0 0 1 0-1.792l48.247-48.247a9.115 9.115 0 0 1 12.926 0 9.115 9.115 0 0 1 0 12.926l-.384.384-51.063 44.792c-.128.255-.384.383-.767.383Zm-6.143-9.342 6.27 6.271 50.167-44.024c2.816-2.304 3.072-6.527.768-9.342-2.303-2.816-6.526-3.072-9.342-.768-.128.128-.256.256-.512.384l-47.351 47.48Z" />
              <path fill="#FFF" d="M80.009 187.637c-.512.256-.768.768-.64 1.28l2.175 9.214c.512 1.28-.256 2.816-1.663 3.2-1.024.384-2.176 0-2.816-.768l-14.077-13.95 45.943-45.943 15.87.256 10.75 10.75c-2.56 2.175-18.045 17.149-55.542 35.961Z" />
              <path fill="#FF6C37" d="M78.985 202.61c-1.024 0-2.048-.383-2.688-1.151l-13.95-13.95c-.255-.256-.383-.512-.383-.896 0-.383.128-.64.384-.895l45.944-45.944c.256-.256.64-.384.895-.384l15.87.256c.383 0 .64.128.895.384l10.75 10.75c.256.256.384.64.384 1.024s-.128.64-.512.896l-.895.767c-13.566 11.902-31.995 23.804-54.902 35.194l2.175 9.086c.384 1.664-.384 3.456-1.92 4.352-.767.384-1.407.512-2.047.512Zm-14.078-15.997 13.182 13.054c.384.64 1.152.896 1.792.512.64-.384.896-1.152.512-1.792l-2.176-9.214c-.256-1.152.256-2.176 1.28-2.688 22.652-11.39 40.952-23.163 54.39-34.81l-9.47-9.47-14.718-.256-44.792 44.664Z" />
              <path fill="#FFF" d="m52.11 197.62 11.006-11.007 16.38 16.381-26.107-1.791c-1.151-.128-1.92-1.152-1.791-2.304 0-.512.128-1.024.512-1.28Z" />
              <path fill="#FF6C37" d="m79.497 204.146-26.236-1.791c-1.92-.128-3.199-1.792-3.071-3.712.128-.768.384-1.535 1.024-2.047L62.22 185.59a1.237 1.237 0 0 1 1.792 0l16.38 16.38c.385.385.512.897.257 1.408-.256.512-.64.768-1.152.768Zm-16.381-15.74-10.11 10.11c-.384.255-.384.895 0 1.151.127.128.255.256.511.256l22.652 1.536-13.053-13.054ZM104.452 146.557c-.768 0-1.28-.64-1.28-1.28 0-.384.128-.64.384-.896l12.414-12.414a1.237 1.237 0 0 1 1.792 0l8.062 8.063c.384.384.512.768.384 1.28-.128.384-.512.767-1.023.895l-20.477 4.352h-.256Zm12.414-11.902-8.446 8.446 13.821-2.943-5.375-5.503Z" />
              <path fill="#FFF" d="m124.8 140.926-14.077 3.071c-1.024.256-2.048-.384-2.303-1.408-.128-.64 0-1.28.511-1.791l7.807-7.807 8.063 7.935Z" />
              <path fill="#FF6C37" d="M110.467 145.277a3.168 3.168 0 0 1-3.2-3.2c0-.895.385-1.663.897-2.303l7.806-7.807a1.237 1.237 0 0 1 1.792 0l8.062 8.063c.384.384.512.768.384 1.28-.128.384-.512.767-1.023.895l-14.078 3.072h-.64Zm6.399-10.622-6.91 6.91c-.257.257-.257.512-.129.768s.384.384.768.384l11.774-2.56-5.503-5.502ZM203.25 64.907c-.256-.767-1.151-1.151-1.92-.895-.767.255-1.151 1.151-.895 1.92 0 .127.128.255.128.383.768 1.536.512 3.455-.512 4.863-.512.64-.384 1.536.128 2.048.64.512 1.536.384 2.048-.256 1.92-2.432 2.303-5.503 1.023-8.063Z" />
            </svg>} />
    </div>;
};

export const ScopesList = ({scopes = [], description = "This API requires one of the following scopes:"}) => {
  if (!scopes || scopes.length === 0) {
    return null;
  }
  const sortedScopes = scopes.sort((a, b) => a.localeCompare(b));
  return <div>
      <div className="text-sm mb-2">{description}</div>
      <div>
        {sortedScopes.map((scope, index) => <div key={index}>
            <code>
              <span className="text-xs">{scope}</span>
            </code>
          </div>)}
      </div>
    </div>;
};

<PostmanCard collectionId="26126890-4b73e107-790f-4e81-8da8-677eb748e2b9" />

<Accordion title="Scope requirements">
  <ScopesList
    scopes={[
  'automation.sequences.enrollments.write',
  'automation.sequences.read'
]}
  />
</Accordion>

To send a series of targeted, timed email templates to nurture contacts over time, you can [create a sequence](https://knowledge.hubspot.com/sequences/create-and-edit-sequences). 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*](https://knowledge.hubspot.com/account-management/manage-seats) [or ***Service Hub** Professional* or *Enterprise* seat](https://knowledge.hubspot.com/account-management/manage-seats).

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.

## Fetch a sequence

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](/api-reference/legacy/crm/objects/users/guide) 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:

<Warning>
  **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.
</Warning>

```json expandable theme={null}
{
  "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/v4/sequences/?limit=#&userId={userId}`. Use the amount of sequences you want returned as the limit in the request URL and use your [userID](/api-reference/legacy/crm/objects/users/guide) 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:

```json expandable theme={null}
{
  "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.      |

## Enroll a contact in a sequence

To enroll a contact in a sequence, make a `POST` request to `/automation/v4/sequences/enrollments/`. Use your [user ID](/api-reference/legacy/crm/objects/users/guide) as the query parameter. Specify the sequenceId, contactId, and senderEmail in the body. The senderEmail must be an email address that's [connected](https://knowledge.hubspot.com/connected-email/connect-your-inbox-to-hubspot) 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:

```json theme={null}
{
  "sequenceId": "33333",
  "contactId": "44444444",
  "senderEmail": "menelson@hubspot.com"
}
```

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

```json theme={null}
{
  "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.) |

<Warning>
  **Please note:**

  There is a limit of 1000 enrollments per portal inbox per day.
</Warning>

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

```json theme={null}
{
  "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. |
