{ "openapi" : "3.0.1", "info" : { "title" : "Sequences", "description" : "Basepom for all HubSpot Projects", "version" : "v4", "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-related-documentation" : [ { "name" : "Sequences Guide", "url" : "https://developers.hubspot.com/docs/guides/api/automation/sequences" } ], "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/v4/sequences" : { "get" : { "tags" : [ "Basic" ], "operationId" : "get-/automation/v4/sequences", "parameters" : [ { "name" : "userId", "in" : "query", "required" : true, "style" : "form", "explode" : true, "schema" : { "type" : "string", "example" : null } }, { "name" : "after", "in" : "query", "required" : false, "style" : "form", "explode" : true, "schema" : { "type" : "string", "example" : null } }, { "name" : "limit", "in" : "query", "required" : false, "style" : "form", "explode" : true, "schema" : { "type" : "integer", "format" : "int32", "example" : null } }, { "name" : "name", "in" : "query", "required" : false, "style" : "form", "explode" : true, "schema" : { "type" : "string", "example" : null } } ], "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CollectionResponseWithTotalPublicSequenceLiteResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "automation.sequences.read" ] } ] } }, "/automation/v4/sequences/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/v4/sequences/enrollments", "parameters" : [ { "name" : "userId", "in" : "query", "description" : "", "required" : true, "style" : "form", "explode" : true, "schema" : { "type" : "string", "example" : null } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PublicSequenceEnrollmentRequest" }, "example" : null } }, "required" : true }, "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PublicSequenceEnrollmentLiteResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "automation.sequences.enrollments.write" ] } ] } }, "/automation/v4/sequences/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/v4/sequences/enrollments/contact/{contactId}", "parameters" : [ { "name" : "contactId", "in" : "path", "description" : "", "required" : true, "style" : "simple", "explode" : false, "schema" : { "type" : "string", "example" : null } } ], "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PublicSequenceEnrollmentResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "automation.sequences.read" ] } ] } }, "/automation/v4/sequences/{sequenceId}" : { "get" : { "tags" : [ "Basic" ], "summary" : "Retrieve details for a sequence", "description" : "Retrieve details of a specific sequence by its ID.", "operationId" : "get-/automation/v4/sequences/{sequenceId}", "parameters" : [ { "name" : "sequenceId", "in" : "path", "description" : "", "required" : true, "style" : "simple", "explode" : false, "schema" : { "type" : "string", "example" : null } }, { "name" : "userId", "in" : "query", "description" : "", "required" : true, "style" : "form", "explode" : true, "schema" : { "type" : "string", "example" : null } } ], "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PublicSequenceResponse" }, "example" : null } } }, "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", "example" : null, "items" : { "$ref" : "#/components/schemas/PublicSequenceLiteResponse" } }, "total" : { "type" : "integer", "format" : "int32", "example" : null } }, "example" : null }, "Error" : { "required" : [ "category", "correlationId", "message" ], "type" : "object", "properties" : { "category" : { "type" : "string", "description" : "The error category", "example" : null }, "context" : { "type" : "object", "additionalProperties" : { "type" : "array", "example" : null, "items" : { "type" : "string", "example" : null } }, "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", "example" : null, "items" : { "$ref" : "#/components/schemas/ErrorDetail" } }, "links" : { "type" : "object", "additionalProperties" : { "type" : "string", "example" : null }, "description" : "A map of link names to associated URIs containing documentation about the error or recommended remediation steps", "example" : null }, "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", "example" : null } }, "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", "example" : null }, "context" : { "type" : "object", "additionalProperties" : { "type" : "array", "example" : null, "items" : { "type" : "string", "example" : null } }, "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.", "example" : null }, "message" : { "type" : "string", "description" : "A human readable message describing the error along with remediation steps where appropriate", "example" : null }, "subCategory" : { "type" : "string", "description" : "A specific category that contains more specific detail about the error", "example" : null } }, "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.", "example" : null }, "NextPage" : { "required" : [ "after" ], "type" : "object", "properties" : { "after" : { "type" : "string", "description" : "A paging cursor token for retrieving subsequent pages.", "example" : null }, "link" : { "type" : "string", "description" : "A URL that can be used to retrieve the next page results.", "example" : null } }, "description" : "Specifies the paging information needed to retrieve the next set of results in a paginated API response", "example" : null }, "Paging" : { "type" : "object", "properties" : { "next" : { "$ref" : "#/components/schemas/NextPage" }, "prev" : { "$ref" : "#/components/schemas/PreviousPage" } }, "description" : "Represents the pagination information for navigating through a list of results in the API. It provides details on how to access the previous or next set of results.", "example" : null }, "PreviousPage" : { "required" : [ "before" ], "type" : "object", "properties" : { "before" : { "type" : "string", "description" : "A paging cursor token for retrieving previous pages.", "example" : null }, "link" : { "type" : "string", "description" : "A URL that can be used to retrieve the previous pages' results.", "example" : null } }, "description" : "specifies the paging information needed to retrieve the previous set of results in a paginated API response", "example" : null }, "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", "example" : null }, "id" : { "type" : "string", "description" : "The unique identifier of the email pattern.", "example" : null }, "templateId" : { "type" : "string", "description" : "The unique identifier of the email template associated with the pattern.", "example" : null }, "threadEmailToStepOrder" : { "type" : "integer", "description" : "The order identifying the previous step to which the email thread is linked.", "format" : "int32", "example" : null }, "updatedAt" : { "type" : "string", "description" : "The date and time when the email pattern was last updated.", "format" : "date-time", "example" : null } }, "example" : null }, "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", "example" : null }, "id" : { "type" : "string", "description" : "The unique identifier for the sequence enrollment.", "example" : null }, "toEmail" : { "type" : "string", "description" : "The email address of the contact enrolled in the sequence.", "example" : null }, "updatedAt" : { "type" : "string", "description" : "The date and time when the sequence enrollment was last updated.", "format" : "date-time", "example" : null } }, "example" : null }, "PublicSequenceEnrollmentRequest" : { "required" : [ "contactId", "senderEmail", "sequenceId" ], "type" : "object", "properties" : { "contactId" : { "type" : "string", "description" : "The unique identifier of the contact to be enrolled in the sequence.", "example" : null }, "senderAliasAddress" : { "type" : "string", "description" : "The alias email address used by the sender when enrolling the contact.", "example" : null }, "senderEmail" : { "type" : "string", "description" : "The email address of the sender enrolling the contact in the sequence.", "example" : null }, "sequenceId" : { "type" : "string", "description" : "The unique identifier of the sequence in which the contact will be enrolled.", "example" : null } }, "example" : null }, "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", "example" : null }, "enrolledBy" : { "type" : "string", "description" : "The identifier of the user who enrolled the contact in the sequence.", "example" : null }, "enrolledByEmail" : { "type" : "string", "description" : "The email address of the user who enrolled the contact in the sequence.", "example" : null }, "id" : { "type" : "string", "description" : "The unique identifier for the sequence enrollment.", "example" : null }, "sequenceId" : { "type" : "string", "description" : "The unique identifier of the sequence in which the contact is enrolled.", "example" : null }, "sequenceName" : { "type" : "string", "description" : "The name of the sequence in which the contact is enrolled.", "example" : null }, "toEmail" : { "type" : "string", "description" : "The email address of the contact enrolled in the sequence.", "example" : null }, "updatedAt" : { "type" : "string", "description" : "The date and time when the sequence enrollment was last updated.", "format" : "date-time", "example" : null } }, "example" : null }, "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", "example" : null }, "folderId" : { "type" : "string", "description" : "The ID of the folder containing the sequence.", "example" : null }, "id" : { "type" : "string", "description" : "The unique identifier of the sequence.", "example" : null }, "name" : { "type" : "string", "description" : "The name of the sequence.", "example" : null }, "updatedAt" : { "type" : "string", "description" : "The date and time when the sequence was last updated.", "format" : "date-time", "example" : null }, "userId" : { "type" : "string", "description" : "The ID of the user associated with the sequence.", "example" : null } }, "example" : null }, "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", "example" : null }, "dependencies" : { "type" : "array", "example" : null, "items" : { "$ref" : "#/components/schemas/PublicSequenceStepDependencyResponse" } }, "folderId" : { "type" : "string", "description" : "The identifier of the folder containing the sequence.", "example" : null }, "id" : { "type" : "string", "description" : "The unique identifier for the sequence.", "example" : null }, "name" : { "type" : "string", "description" : "The name of the sequence.", "example" : null }, "settings" : { "$ref" : "#/components/schemas/PublicSequenceSettingsResponse" }, "steps" : { "type" : "array", "example" : null, "items" : { "$ref" : "#/components/schemas/PublicSequenceStepResponse" } }, "updatedAt" : { "type" : "string", "description" : "The date and time when the sequence was last updated.", "format" : "date-time", "example" : null }, "userId" : { "type" : "string", "description" : "The ID of the user associated with the sequence.", "example" : null } }, "example" : null }, "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", "example" : null }, "eligibleFollowUpDays" : { "type" : "string", "description" : "Specifies the days on which follow-up actions are allowed.", "example" : null, "enum" : [ "BUSINESS_DAYS", "EVERYDAY", "WEEKDAYS_ONLY" ] }, "id" : { "type" : "string", "description" : "The unique identifier for the sequence settings.", "example" : null }, "individualTaskRemindersEnabled" : { "type" : "boolean", "description" : "Indicates whether individual task reminders are enabled.", "example" : null }, "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.", "example" : null, "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", "example" : null }, "sendWindowStartMinute" : { "type" : "integer", "description" : "Indicates the start minute of the time window during which automated emails can be sent.", "format" : "int32", "example" : null }, "taskReminderMinute" : { "type" : "integer", "description" : "Specifies the minute of day at which task reminders are triggered.", "format" : "int32", "example" : null }, "updatedAt" : { "type" : "string", "description" : "The timestamp of when the sequence settings were last updated.", "format" : "date-time", "example" : null } }, "example" : null }, "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", "example" : null }, "dependencyType" : { "type" : "string", "description" : "The type of dependency between sequence steps with accepted values being TASK_COMPLETION or MANUAL_PAUSE.", "example" : null, "enum" : [ "ADAPTIVE_COMPLETION", "MANUAL_PAUSE", "TASK_COMPLETION" ] }, "id" : { "type" : "string", "description" : "The unique identifier of the step dependency.", "example" : null }, "reliesOnSequenceStepId" : { "type" : "string", "description" : "The unique identifier of the sequence step that is responsible for creating and resolving this dependency.", "example" : null }, "reliesOnStepOrder" : { "type" : "integer", "description" : "The order number of the step that is responsible for creating and resolving this dependency.", "format" : "int32", "example" : null }, "requiredBySequenceStepId" : { "type" : "string", "description" : "The unique identifier of the sequence step that requires this dependency.", "example" : null }, "requiredByStepOrder" : { "type" : "integer", "description" : "The order number of the step that requires this dependency.", "format" : "int32", "example" : null }, "updatedAt" : { "type" : "string", "description" : "The date and time when the step dependency was last updated.", "format" : "date-time", "example" : null } }, "example" : null }, "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.", "example" : null, "enum" : [ "ADAPTIVE_CONTAINER", "EMAIL", "FINISH_ENROLLMENT", "TASK" ] }, "createdAt" : { "type" : "string", "description" : "The date and time when the sequence step was created.", "format" : "date-time", "example" : null }, "delayMillis" : { "type" : "integer", "description" : "The delay in milliseconds before the sequence step is executed.", "format" : "int64", "example" : null }, "emailPattern" : { "$ref" : "#/components/schemas/PublicEmailPatternResponse" }, "id" : { "type" : "string", "description" : "The unique identifier of the sequence step.", "example" : null }, "stepOrder" : { "type" : "integer", "description" : "The order of the step within the sequence.", "format" : "int32", "example" : null }, "taskPattern" : { "$ref" : "#/components/schemas/PublicTaskPatternResponse" }, "updatedAt" : { "type" : "string", "description" : "The date and time when the sequence step was last updated.", "format" : "date-time", "example" : null } }, "example" : null }, "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", "example" : null }, "id" : { "type" : "string", "description" : "The unique identifier for the task pattern.", "example" : null }, "notes" : { "type" : "string", "description" : "Additional notes or comments associated with the task.", "example" : null }, "queueId" : { "type" : "integer", "description" : "The identifier for the queue associated with the task.", "format" : "int32", "example" : null }, "subject" : { "type" : "string", "description" : "The subject line of the task.", "example" : null }, "taskPriority" : { "type" : "string", "description" : "The priority level assigned to the task.", "example" : null, "enum" : [ "HIGH", "LOW", "MEDIUM", "NONE" ] }, "taskType" : { "type" : "string", "description" : "The type of task, such as an email or call.", "example" : null, "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", "example" : null }, "threadEmailToStepOrder" : { "type" : "integer", "description" : "The order of the step to which the email thread is related.", "format" : "int32", "example" : null }, "updatedAt" : { "type" : "string", "description" : "The date and time when the task pattern was last updated.", "format" : "date-time", "example" : null } }, "example" : null } }, "responses" : { "Error" : { "description" : "An error occurred.", "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/Error" }, "example" : null } } } }, "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" } }