{ "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 } }, "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 } }, "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" } }, "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" } }