> ## 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. # Workflows API (BETA) > Learn how to use the Workflows API. export const BetaDisclaimerBanner = () => This functionality is currently in beta. By participating in this beta, you agree to HubSpot's Developer Terms and Developer Beta Terms. Note that the functionality is still under active development and is subject to change based on testing and feedback. ; 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
{description}
{sortedScopes.map((scope, index) =>
{scope}
)}
; }; Use the workflows API to fetch data from existing [workflows](https://knowledge.hubspot.com/workflows/create-workflows), create new workflows, and delete workflows that you no longer need. The sections below provide a walkthrough of how to use these endpoints. When setting up your requests, learn more about [action and enrollment types](/docs/api-reference/legacy/automation/workflows/action-enrollment-reference). ## Scope requirements To use any of the endpoints, your app will need to be authorized to use the `automation` scope. In addition, if you need to access sensitive data properties in a workflow, enroll records in a workflow that references sensitive data, or retrieve enrollment and performance data for workflows with sensitive data properties, you'll need to authorize sensitive data scopes as detailed in the sections below. Learn more about [working with sensitive data](https://knowledge.hubspot.com/account-security/store-sensitive-data). ### Retrieving workflows that reference sensitive data To retrieve enrollment and performance data for existing workflows that reference sensitive data properties, your app will need to request and be granted one of the scopes below, based on the enrolled record type in your workflow: * `crm.objects.contacts.sensitive.read`: view enrollment and performance data for existing contact-based workflows. * `crm.objects.companies.sensitive.read`: view enrollment and performance data for existing company-based workflows. * `crm.objects.deals.sensitive.read`: view enrollment and performance data for existing deal-based workflows. * `crm.objects.custom.sensitive.read`: view enrollment and performance data for workflows based on custom objects an account. The scopes above are not sufficient to create or delete workflows using this API, or enroll records in existing workflows that access sensitive data properties. Consult the sensitive data write scopes in the section below if you need to perform these operations via this API. ### Creating and managing workflows that reference sensitive data To create or delete workflows that reference sensitive data, or enroll records in an existing workflow, your app will need to request and be granted one of the scopes below, based on the enrolled record type of your workflow: * `crm.objects.contacts.sensitive.write`: create and delete contact-based workflows via this API, as well as enroll contacts in existing workflows that access sensitive data. * `crm.objects.companies.sensitive.write`: create and delete company-based workflows via this API, as well as enroll companies in existing workflows that access sensitive data. * `crm.objects.deals.sensitive.write`: create and delete deal-based workflows via this API, as well as enroll deals in existing workflows that access sensitive data. * `crm.objects.custom.sensitive.write`: create and delete workflows based on custom objects via this API, as well as enroll custom object records in existing workflows that access sensitive data. ## Create a workflow To create a workflow, make a `POST` request to `/automation/v4/2027-03-beta/flows` and provide a workflow specification in the body of your request. * Consult the [action and enrollment types reference](/docs/api-reference/legacy/automation/workflows/action-enrollment-reference) for information on specifying the `actions` in your workflow and configuring the `enrollmentCriteria`. * For contact-based workflows, set the `type` to `CONTACT_FLOW`. For all other workflow types (e.g., deal-based, goal-based, etc.), set the `type` to `PLATFORM_FLOW`. For example, if you wanted to create a workflow that executed the following: * When a contact submits a specific form on your website, create a ticket in your account. * After a 1 day delay, send an [automated marketing email](https://knowledge.hubspot.com/marketing-email/create-automated-emails-to-use-in-workflows) to the contact. The request body of your `POST` request will resemble the following: ```json theme={null} { "isEnabled": true, "flowType": "WORKFLOW", "name": "New form submission from interested contact", "startActionId": "1", "nextAvailableActionId": "4", "actions": [ { "type": "SINGLE_CONNECTION", "actionId": "1", "actionTypeVersion": 0, "actionTypeId": "0-14", "connection": { "edgeType": "STANDARD", "nextActionId": "3" }, "fields": { "object_type_id": "0-5", "properties": [ { "targetProperty": "subject", "value": { "type": "STATIC_VALUE", "staticValue": "Review new form submission" } }, { "targetProperty": "hs_pipeline_stage", "value": { "type": "STATIC_VALUE", "staticValue": "1" } }, { "targetProperty": "source_type", "value": { "type": "STATIC_VALUE", "staticValue": "FORM" } }, { "targetProperty": "content", "value": { "type": "STATIC_VALUE", "staticValue": "[Triage required] new form submitted. Next available rep should review." } } ], "associations": [ { "target": { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 16 }, "value": { "type": "ENROLLED_OBJECT" } }, { "target": { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 339 }, "value": { "type": "COPY_ASSOCIATION", "sourceSpec": { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 279 } } } ], "use_explicit_associations": "true" } }, { "type": "SINGLE_CONNECTION", "actionId": "2", "actionTypeVersion": 0, "actionTypeId": "0-4", "fields": { "content_id": "113782603056" } }, { "type": "SINGLE_CONNECTION", "actionId": "3", "actionTypeVersion": 0, "actionTypeId": "0-1", "connection": { "edgeType": "STANDARD", "nextActionId": "2" }, "fields": { "delta": "1440", "time_unit": "MINUTES" } } ], "enrollmentCriteria": { "shouldReEnroll": false, "type": "EVENT_BASED", "eventFilterBranches": [ { "filterBranches": [], "filters": [ { "property": "hs_form_id", "operation": { "operator": "IS_ANY_OF", "includeObjectsWithNoValueSet": false, "values": ["2f5cc7f8-d359-4e9c-a770-dd42ea07d217"], "operationType": "ENUMERATION" }, "filterType": "PROPERTY" } ], "eventTypeId": "4-1639801", "operator": "HAS_COMPLETED", "filterBranchType": "UNIFIED_EVENTS", "filterBranchOperator": "AND" } ], "listMembershipFilterBranches": [] }, "timeWindows": [], "blockedDates": [], "customProperties": {}, "crmObjectCreationStatus": "COMPLETE", "type": "CONTACT_FLOW", "objectTypeId": "0-1", "suppressionListIds": [], "canEnrollFromSalesforce": false } ``` ## Retrieve workflows The sections below outline how to fetch details about specific workflows, or retrieve details for multiple workflows in a single call. When retrieving workflows, you may need the workflow's `flowId` to make a request. To retrieve the workflow's `flowId`: * In your HubSpot account, navigate to the [workflow editor](https://knowledge.hubspot.com/workflows/organize-your-workflows#manage-your-workflows) for the workflow that you'd like to retrieve, then check the URL for the second ID in the URL path. * Alternatively, make a `GET` request to `/automation/v4/2027-03-beta/flows` to get all workflows and filter the resulting response by the name of your workflow. workflow-id-for-automation-v4-api-1 ### Retrieve a specific workflow by ID To retrieve data from an existing workflow, make a `GET` request to `/automation/v4/2027-03-beta/flows/{flowId}`, where `flowId` is the ID of an existing workflow in your account. For example, if you made a `GET` request to `/automation/v4/2027-03-beta/flows/12345678` to get the workflow with an ID of `12345678`, you can expect the resulting response below. The response includes the specification for a contact-based workflow with two actions, where contacts are enrolled if they filled out a form on your website. If there are actions with incomplete but required fields in your workflow, you may encounter errors when making this request. ```json theme={null} { "id": "12345678", "isEnabled": true, "flowType": "WORKFLOW", "revisionId": "7", "name": "New form submission workflow", "createdAt": "2024-06-07T17:27:08.101Z", "updatedAt": "2024-06-07T17:31:11.263Z", "startActionId": "1", "nextAvailableActionId": "3", "actions": [ { "type": "SINGLE_CONNECTION", "actionId": "1", "actionTypeVersion": 0, "actionTypeId": "0-13", "connection": { "edgeType": "STANDARD", "nextActionId": "2" }, "fields": { "operation": "ADD", "list_id": "178" } }, { "type": "SINGLE_CONNECTION", "actionId": "2", "actionTypeVersion": 0, "actionTypeId": "0-9", "fields": { "user_ids": ["2620022"], "delivery_method": "APP", "subject": "New form submission", "body": "Check out the new form submission we received!" } } ], "enrollmentCriteria": { "shouldReEnroll": false, "type": "EVENT_BASED", "eventFilterBranches": [ { "filterBranches": [], "filters": [], "eventTypeId": "4-1639801", "operator": "HAS_COMPLETED", "filterBranchType": "UNIFIED_EVENTS", "filterBranchOperator": "AND" } ], "listMembershipFilterBranches": [] }, "timeWindows": [], "blockedDates": [], "customProperties": {}, "crmObjectCreationStatus": "COMPLETE", "type": "CONTACT_FLOW", "objectTypeId": "0-1", "suppressionListIds": [], "canEnrollFromSalesforce": false } ``` ### Retrieve workflows in bulk using their IDs To fetch multiple workflows using their IDs, you can make a `POST` request to the `/automation/v4/2027-03-beta/flows/batch/read` endpoint. When doing so, you'll need to provide the following within an `inputs` array provided in the request body: * The ID of each workflow as the `flowId`. * The `type` as `FLOW_ID` For example, the request body below would fetch the workflow details for two workflows with IDs of `12345678` and `87654321`: ```json theme={null} { "inputs": [ { "flowId": "12345678", "type": "FLOW_ID" }, { "flowId": "87654321", "type": "FLOW_ID" } ] } ``` ### Retrieve all workflows To retrieve all workflows in an account, you can make a `GET` request to `/automation/v4/2027-03-beta/flows`. Do note that the response will only include key fields for the workflow, such as `id`, `isEnabled`, `objectTypeId`, and the latest `revisionId`. If you want to retrieve a full list of properties for a specific workflow, make a `GET` request to `/automation/v4/2027-03-beta/flows/{flowId}` and provide the specific ID of the workflow as the `flowId`. ## Update a workflow To update an existing workflow, make a `PUT` request to `/automation/v4/2027-03-beta/flows/{flowId}` using the ID of your workflow you want to update as the `flowId`, and providing any properties you want to change in the request body. * You must include the `revisionId` and `type` properties in your request body. * The `revisionId` must correspond to the most current revision of your workflow. This can be retrieved by making a `GET` request to `/automation/v4/2027-03-beta/flows/{flowId}`. * Any existing data retrieved from the `GET` request, not included in the `PUT` request, will be omitted from the updated workflow. For example, if an existing action is not included in the new `PUT` request to update the workflow, the action will be removed from the workflow. * If you're creating a `PUT` request with data retrieved from an earlier `GET` request, it is recommended to remove the `CreatedAt`, `UpdatedAt`, and `dataSources` fields to avoid validation errors. For the example, if the following workflow is currently turned off, the request body below would turn on the workflow, using its most recent revisionId of `"18"`: ```json theme={null} { "id": "1734596242", "isEnabled": true, "flowType": "WORKFLOW", "revisionId": "18", "name": "Contact Us Simple Flow [2025]", "startActionId": "4", "nextAvailableActionId": "6", "actions": [ { "actionId": "4", "actionTypeVersion": 0, "actionTypeId": "0-1", "connection": { "edgeType": "STANDARD", "nextActionId": "5" }, "fields": { "delta": "1440", "time_unit": "MINUTES" }, "type": "SINGLE_CONNECTION" }, { "actionId": "5", "actionTypeVersion": 0, "actionTypeId": "0-4", "fields": { "content_id": "35431921489" }, "type": "SINGLE_CONNECTION" } ], "enrollmentCriteria": { "shouldReEnroll": true, "eventFilterBranches": [ { "filterBranches": [], "filters": [ { "property": "hs_form_id", "operation": { "operator": "IS_ANY_OF", "includeObjectsWithNoValueSet": false, "values": [ "1c2c34c5-c98b-4241-abea-ef227575335b" ], "operationType": "ENUMERATION" }, "filterType": "PROPERTY" } ], "eventTypeId": "4-1639801", "operator": "HAS_COMPLETED", "filterBranchType": "UNIFIED_EVENTS", "filterBranchOperator": "AND" } ], "listMembershipFilterBranches": [], "type": "EVENT_BASED" }, "timeWindows": [], "blockedDates": [], "customProperties": {}, "crmObjectCreationStatus": "COMPLETE", "suppressionListIds": [], "canEnrollFromSalesforce": false, "type": "CONTACT_FLOW", "objectTypeId": "0-1" } ``` ## Delete a workflow To delete a workflow, make a `DELETE` request to `/automation/v4/2027-03-beta/flows/{flowId}` using the ID of the workflow you want to delete as the `flowId`. **Please note:** once deleted, you cannot restore the workflow via the automation API. You must [contact HubSpot Support](https://knowledge.hubspot.com/help-and-resources/get-help-with-hubspot) to get assistance with restoring your workflow.