HubSpot Automation Sequences API

openapi: 3.0.1
info:
  title: HubSpot Automation Sequences
  description: Basepom for all HubSpot Projects
  version: 2026-03
  x-hubspot-product-tier-requirements:
    marketing: FREE
    sales: PROFESSIONAL
    service: PROFESSIONAL
    cms: FREE
    commerce: FREE
    crmHub: FREE
    dataHub: FREE
  x-hubspot-api-use-case: You need to enroll them in a HubSpot sequence using an app you designed to maintain
    a list of contacts.
  x-hubspot-introduction: Use the Sequences API to get a list of sequences get a specific sequence, enroll
    a contact in a sequence, and view a contact’s enrollment status.
servers:
- url: https://api.hubapi.com
tags:
- name: Basic
paths:
  /automation/sequences/2026-03:
    get:
      tags:
      - Basic
      operationId: get-/automation/sequences/2026-03_/automation/sequences/2026-03
      parameters:
      - name: userId
        in: query
        required: true
        style: form
        explode: true
        schema:
          type: string
      - name: after
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: limit
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      - name: name
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponseWithTotalPublicSequenceLiteResponse'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - automation.sequences.read
  /automation/sequences/2026-03/enrollments:
    post:
      tags:
      - Basic
      summary: Enroll a contact in a sequence
      description: Enroll a contact into a sequence using the specified user ID and sequence details.
      operationId: post-/automation/sequences/2026-03/enrollments
      parameters:
      - name: userId
        in: query
        description: ''
        required: true
        style: form
        explode: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicSequenceEnrollmentRequest'
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicSequenceEnrollmentLiteResponse'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - automation.sequences.enrollments.write
  /automation/sequences/2026-03/enrollments/contact/{contactId}:
    get:
      tags:
      - Basic
      summary: Retrieve the enrollment status of a contact
      description: Get the enrollment status of a contact in sequences by their contact ID.
      operationId: get-/automation/sequences/2026-03/enrollments/contact/{contactId}
      parameters:
      - name: contactId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicSequenceEnrollmentResponse'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - automation.sequences.read
  /automation/sequences/2026-03/{sequenceId}:
    get:
      tags:
      - Basic
      summary: Retrieve details for a sequence
      description: Retrieve details of a specific sequence by its ID.
      operationId: get-/automation/sequences/2026-03/{sequenceId}
      parameters:
      - name: sequenceId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: userId
        in: query
        description: ''
        required: true
        style: form
        explode: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicSequenceResponse'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - automation.sequences.read
components:
  schemas:
    CollectionResponseWithTotalPublicSequenceLiteResponse:
      required:
      - results
      - total
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/Paging'
        results:
          type: array
          description: An array of PublicSequenceLiteResponse objects, each representing a lightweight
            version of a sequence.
          items:
            $ref: '#/components/schemas/PublicSequenceLiteResponse'
        total:
          type: integer
          description: An integer representing the total number of sequence items available.
          format: int32
    Error:
      required:
      - category
      - correlationId
      - message
      type: object
      properties:
        category:
          type: string
          description: The error category
        context:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Context about the error condition
          example: '{invalidPropertyName=[propertyValue], missingScopes=[scope1, scope2]}'
        correlationId:
          type: string
          description: A unique identifier for the request. Include this value with any error reports
            or support tickets
          format: uuid
          example: aeb5f871-7f07-4993-9211-075dc63e7cbf
        errors:
          type: array
          description: further information about the error
          items:
            $ref: '#/components/schemas/ErrorDetail'
        links:
          type: object
          additionalProperties:
            type: string
          description: A map of link names to associated URIs containing documentation about the error
            or recommended remediation steps
        message:
          type: string
          description: A human readable message describing the error along with remediation steps where
            appropriate
          example: An error occurred
        subCategory:
          type: string
          description: A specific category that contains more specific detail about the error
      description: Represents an error response returned by the API when an operation fails. This component
        is used in various endpoints to provide detailed information about the error encountered.
      example:
        message: Invalid input (details will vary based on the error)
        correlationId: aeb5f871-7f07-4993-9211-075dc63e7cbf
        category: VALIDATION_ERROR
        links:
          knowledge-base: https://www.hubspot.com/products/service/knowledge-base
    ErrorDetail:
      required:
      - message
      type: object
      properties:
        code:
          type: string
          description: The status code associated with the error detail
        context:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Context about the error condition
          example: '{missingScopes=[scope1, scope2]}'
        in:
          type: string
          description: The name of the field or parameter in which the error was found.
        message:
          type: string
          description: A human readable message describing the error along with remediation steps where
            appropriate
        subCategory:
          type: string
          description: A specific category that contains more specific detail about the error
      description: Represents detailed information about an error that occurred in the API. This component
        is used to provide additional context and specifics about errors, typically as part of an error
        response.
    NextPage:
      required:
      - after
      type: object
      properties:
        after:
          type: string
          description: A paging cursor token for retrieving subsequent pages.
        link:
          type: string
          description: A URL that can be used to retrieve the next page results.
      description: Specifies the paging information needed to retrieve the next set of results in a paginated
        API response
    Paging:
      type: object
      properties:
        next:
          $ref: '#/components/schemas/NextPage'
        prev:
          $ref: '#/components/schemas/PreviousPage'
    PreviousPage:
      required:
      - before
      type: object
      properties:
        before:
          type: string
          description: A string token used to identify the position before the current page in the pagination
            sequence.
        link:
          type: string
          description: A URL string that provides a direct link to the previous page of results.
      description: specifies the paging information needed to retrieve the previous set of results in
        a paginated API response
    PublicEmailPatternResponse:
      required:
      - createdAt
      - id
      - templateId
      - updatedAt
      type: object
      properties:
        createdAt:
          type: string
          description: The date and time when the email pattern was created.
          format: date-time
        id:
          type: string
          description: The unique identifier of the email pattern.
        templateId:
          type: string
          description: The unique identifier of the email template associated with the pattern.
        threadEmailToStepOrder:
          type: integer
          description: The order identifying the previous step to which the email thread is linked.
          format: int32
        updatedAt:
          type: string
          description: The date and time when the email pattern was last updated.
          format: date-time
    PublicSequenceEnrollmentLiteResponse:
      required:
      - enrolledAt
      - id
      - toEmail
      - updatedAt
      type: object
      properties:
        enrolledAt:
          type: string
          description: The date and time when the contact was enrolled in the sequence.
          format: date-time
        id:
          type: string
          description: The unique identifier for the sequence enrollment.
        toEmail:
          type: string
          description: The email address of the contact enrolled in the sequence.
        updatedAt:
          type: string
          description: The date and time when the sequence enrollment was last updated.
          format: date-time
    PublicSequenceEnrollmentRequest:
      required:
      - contactId
      - senderEmail
      - sequenceId
      type: object
      properties:
        contactId:
          type: string
          description: The unique identifier of the contact to be enrolled in the sequence.
        senderAliasAddress:
          type: string
          description: The alias email address used by the sender when enrolling the contact.
        senderEmail:
          type: string
          description: The email address of the sender enrolling the contact in the sequence.
        sequenceId:
          type: string
          description: The unique identifier of the sequence in which the contact will be enrolled.
    PublicSequenceEnrollmentResponse:
      required:
      - enrolledAt
      - enrolledBy
      - enrolledByEmail
      - id
      - sequenceId
      - sequenceName
      - toEmail
      - updatedAt
      type: object
      properties:
        enrolledAt:
          type: string
          description: The date and time when the contact was enrolled in the sequence.
          format: date-time
        enrolledBy:
          type: string
          description: The identifier of the user who enrolled the contact in the sequence.
        enrolledByEmail:
          type: string
          description: The email address of the user who enrolled the contact in the sequence.
        id:
          type: string
          description: The unique identifier for the sequence enrollment.
        sequenceId:
          type: string
          description: The unique identifier of the sequence in which the contact is enrolled.
        sequenceName:
          type: string
          description: The name of the sequence in which the contact is enrolled.
        toEmail:
          type: string
          description: The email address of the contact enrolled in the sequence.
        updatedAt:
          type: string
          description: The date and time when the sequence enrollment was last updated.
          format: date-time
    PublicSequenceLiteResponse:
      required:
      - createdAt
      - id
      - name
      - updatedAt
      - userId
      type: object
      properties:
        createdAt:
          type: string
          description: The date and time when the sequence was created.
          format: date-time
        folderId:
          type: string
          description: The ID of the folder containing the sequence.
        id:
          type: string
          description: The unique identifier of the sequence.
        name:
          type: string
          description: The name of the sequence.
        updatedAt:
          type: string
          description: The date and time when the sequence was last updated.
          format: date-time
        userId:
          type: string
          description: The ID of the user associated with the sequence.
    PublicSequenceResponse:
      required:
      - createdAt
      - dependencies
      - id
      - name
      - steps
      - updatedAt
      - userId
      type: object
      properties:
        createdAt:
          type: string
          description: The date and time when the sequence was created.
          format: date-time
        dependencies:
          type: array
          description: An array of dependencies for the sequence steps, each represented as a PublicSequenceStepDependencyResponse
            object.
          items:
            $ref: '#/components/schemas/PublicSequenceStepDependencyResponse'
        folderId:
          type: string
          description: The identifier of the folder containing the sequence.
        id:
          type: string
          description: The unique identifier for the sequence.
        name:
          type: string
          description: The name of the sequence.
        settings:
          $ref: '#/components/schemas/PublicSequenceSettingsResponse'
        steps:
          type: array
          description: An array of steps included in the sequence, each represented by a PublicSequenceStepResponse
            object.
          items:
            $ref: '#/components/schemas/PublicSequenceStepResponse'
        updatedAt:
          type: string
          description: The date and time when the sequence was last updated.
          format: date-time
        userId:
          type: string
          description: The ID of the user associated with the sequence.
    PublicSequenceSettingsResponse:
      required:
      - createdAt
      - eligibleFollowUpDays
      - id
      - individualTaskRemindersEnabled
      - sellingStrategy
      - sendWindowEndMinute
      - sendWindowStartMinute
      - taskReminderMinute
      - updatedAt
      type: object
      properties:
        createdAt:
          type: string
          description: The timestamp of when the sequence settings were created.
          format: date-time
        eligibleFollowUpDays:
          type: string
          description: Specifies the days on which follow-up actions are allowed.
          enum:
          - BUSINESS_DAYS
          - EVERYDAY
          - WEEKDAYS_ONLY
        id:
          type: string
          description: The unique identifier for the sequence settings.
        individualTaskRemindersEnabled:
          type: boolean
          description: Indicates whether individual task reminders are enabled.
        sellingStrategy:
          type: string
          description: (deprecated) Defines the unenrollment strategy, with accepted values being ACCOUNT_BASED
            or LEAD_BASED. If ACCOUNT_BASED is used, all contacts associated with the same company will
            be unenrolled if one contact meets any of the unenrollment criteria.
          enum:
          - ACCOUNT_BASED
          - LEAD_BASED
        sendWindowEndMinute:
          type: integer
          description: Indicates the end minute of the time window during which automated emails can be
            sent.
          format: int32
        sendWindowStartMinute:
          type: integer
          description: Indicates the start minute of the time window during which automated emails can
            be sent.
          format: int32
        taskReminderMinute:
          type: integer
          description: Specifies the minute of day at which task reminders are triggered.
          format: int32
        updatedAt:
          type: string
          description: The timestamp of when the sequence settings were last updated.
          format: date-time
    PublicSequenceStepDependencyResponse:
      required:
      - createdAt
      - dependencyType
      - id
      - reliesOnSequenceStepId
      - reliesOnStepOrder
      - requiredBySequenceStepId
      - requiredByStepOrder
      - updatedAt
      type: object
      properties:
        createdAt:
          type: string
          description: The date and time when the step dependency was created.
          format: date-time
        dependencyType:
          type: string
          description: The type of dependency between sequence steps with accepted values being TASK_COMPLETION
            or MANUAL_PAUSE.
          enum:
          - ADAPTIVE_COMPLETION
          - MANUAL_PAUSE
          - TASK_COMPLETION
        id:
          type: string
          description: The unique identifier of the step dependency.
        reliesOnSequenceStepId:
          type: string
          description: The unique identifier of the sequence step that is responsible for creating and
            resolving this dependency.
        reliesOnStepOrder:
          type: integer
          description: The order number of the step that is responsible for creating and resolving this
            dependency.
          format: int32
        requiredBySequenceStepId:
          type: string
          description: The unique identifier of the sequence step that requires this dependency.
        requiredByStepOrder:
          type: integer
          description: The order number of the step that requires this dependency.
          format: int32
        updatedAt:
          type: string
          description: The date and time when the step dependency was last updated.
          format: date-time
    PublicSequenceStepResponse:
      required:
      - actionType
      - createdAt
      - delayMillis
      - id
      - stepOrder
      - updatedAt
      type: object
      properties:
        actionType:
          type: string
          description: The type of action to be performed in the sequence step.
          enum:
          - ADAPTIVE_CONTAINER
          - EMAIL
          - FINISH_ENROLLMENT
          - TASK
        createdAt:
          type: string
          description: The date and time when the sequence step was created.
          format: date-time
        delayMillis:
          type: integer
          description: The delay in milliseconds before the sequence step is executed.
          format: int64
        emailPattern:
          $ref: '#/components/schemas/PublicEmailPatternResponse'
        id:
          type: string
          description: The unique identifier of the sequence step.
        stepOrder:
          type: integer
          description: The order of the step within the sequence.
          format: int32
        taskPattern:
          $ref: '#/components/schemas/PublicTaskPatternResponse'
        updatedAt:
          type: string
          description: The date and time when the sequence step was last updated.
          format: date-time
    PublicTaskPatternResponse:
      required:
      - createdAt
      - id
      - taskPriority
      - taskType
      - updatedAt
      type: object
      properties:
        createdAt:
          type: string
          description: The date and time when the task pattern was created.
          format: date-time
        id:
          type: string
          description: The unique identifier for the task pattern.
        notes:
          type: string
          description: Additional notes or comments associated with the task.
        queueId:
          type: integer
          description: The identifier for the queue associated with the task.
          format: int32
        subject:
          type: string
          description: The subject line of the task.
        taskPriority:
          type: string
          description: The priority level assigned to the task.
          enum:
          - HIGH
          - LOW
          - MEDIUM
          - NONE
        taskType:
          type: string
          description: The type of task, such as an email or call.
          enum:
          - CALL
          - EMAIL
          - LINKED_IN_CONNECT
          - LINKED_IN_MESSAGE
          - MEETING
          - TODO
        templateId:
          type: integer
          description: The identifier for the template used in the task.
          format: int64
        threadEmailToStepOrder:
          type: integer
          description: The order of the step to which the email thread is related.
          format: int32
        updatedAt:
          type: string
          description: The date and time when the task pattern was last updated.
          format: date-time
  responses:
    Error:
      description: An error occurred.
      content:
        '*/*':
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    developer_hapikey:
      type: apiKey
      name: hapikey
      in: query
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.hubspot.com/oauth/authorize
          tokenUrl: https://api.hubapi.com/oauth/v1/token
          scopes:
            automation.sequences.enrollments.write: ''
            automation.sequences.read: ''
    private_apps:
      type: apiKey
      name: private-app
      in: header
    private_apps_legacy:
      type: apiKey
      name: private-app-legacy
      in: header
x-hubspot-product-tier-requirements:
  marketing: FREE
  sales: PROFESSIONAL
  service: PROFESSIONAL
  cms: FREE
  commerce: FREE
  crmHub: FREE
  dataHub: FREE