HubSpot Custom Workflow Actions API

openapi: 3.1.0
info:
  title: HubSpot Custom Workflow Actions API
  description: |
    The HubSpot Custom Workflow Actions API enables developers to create, manage, and extend workflow 
    automation capabilities within HubSpot. This API allows you to define custom actions that can be 
    used in HubSpot workflows, manage action functions, handle callbacks for asynchronous operations, 
    and track revisions of action definitions.

    Key features include:
    - Create and manage custom workflow action definitions
    - Define input and output fields for actions
    - Implement serverless functions for pre and post action execution
    - Handle asynchronous callbacks for long-running operations
    - Track revision history for action definitions
  version: 4.0.0
  contact:
    name: HubSpot Developer Support
    url: https://developers.hubspot.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
- url: https://api.hubapi.com
  description: HubSpot Production API

tags:
- name: Action Definitions
  description: Operations to create and manage custom workflow action definitions
- name: Action Functions
  description: Operations to manage serverless functions associated with action definitions
- name: Definition Revisions
  description: Operations to view revision history of action definitions

- name: Workflow Callbacks
  description: Operations to complete workflow action callbacks for asynchronous actions
paths:
  /automation/v4/actions/callbacks/{callbackId}/complete:
    post:
      tags:
      - Workflow Callbacks
      summary: Hubspot Complete a Single Callback
      description: |
        Completes a single callback for an asynchronous workflow action, providing the output 
        values to continue the workflow execution. Use this endpoint when your action has 
        finished processing and needs to return results to HubSpot.
      operationId: completeCallback
      x-microcks-operation:
        delay: 100
        dispatcher: SCRIPT
        dispatcherRules: |
          def response = mockRequest.requestContent
          return "CallbackCompletionSuccessExample"
      security:
      - oauth2:
        - automation
      parameters:
      - $ref: '#/components/parameters/CallbackIdPath'
        example: example-value
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CallbackCompletionRequest'
            examples:
              CallbackCompletionRequestExample:
                $ref: '#/components/examples/CallbackCompletionRequestExample'
      responses:
        '204':
          description: Callback completed successfully
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                ErrorBadRequestExample:
                  $ref: '#/components/examples/ErrorBadRequestExample'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Completecallback401Example:
                  summary: Default completeCallback 401 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: &id001
                    - message: This is an example description.
                      code: example-value
                      in: example-value
                      subCategory: standard
                      context:
                        key: value
                    context: &id002
                      key: value
                    links: &id003
                      key: value
        '404':
          description: Callback not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                ErrorNotFoundExample:
                  $ref: '#/components/examples/ErrorNotFoundExample'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

              examples:
                Completecallback500Example:
                  summary: Default completeCallback 500 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
  /automation/v4/actions/callbacks/complete:
    post:
      tags:
      - Workflow Callbacks
      summary: Hubspot Complete Multiple Callbacks
      description: |
        Completes multiple callbacks for asynchronous workflow actions in a single request. 
        This is useful when your action processes multiple items and needs to return results 
        for each callback simultaneously.
      operationId: batchCompleteCallbacks
      x-microcks-operation:
        delay: 150
        dispatcher: SCRIPT
        dispatcherRules: |
          def response = mockRequest.requestContent
          return "BatchCallbackCompletionSuccessExample"
      security:
      - oauth2:
        - automation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchCallbackCompletionRequest'
            examples:
              BatchCallbackCompletionRequestExample:
                $ref: '#/components/examples/BatchCallbackCompletionRequestExample'
      responses:
        '204':
          description: All callbacks completed successfully
        '207':
          description: Multi-status - Some callbacks succeeded, some failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchCallbackResponse'
              examples:
                BatchCallbackPartialSuccessExample:
                  $ref: '#/components/examples/BatchCallbackPartialSuccessExample'
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Batchcompletecallbacks400Example:
                  summary: Default batchCompleteCallbacks 400 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Batchcompletecallbacks401Example:
                  summary: Default batchCompleteCallbacks 401 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

              examples:
                Batchcompletecallbacks500Example:
                  summary: Default batchCompleteCallbacks 500 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
  /automation/v4/actions/{appId}:
    get:
      tags:
      - Action Definitions
      summary: Hubspot List Action Definitions
      description: |
        Retrieves a paginated list of all custom action definitions for the specified 
        application. Use query parameters to filter by archived status and control pagination.
      operationId: listActionDefinitions
      x-microcks-operation:
        delay: 100
        dispatcher: SCRIPT
        dispatcherRules: |
          def response = mockRequest.requestContent
          return "ActionDefinitionCollectionSuccessExample"
      security:
      - oauth2:
        - automation
      - privateApp: []
      parameters:
      - $ref: '#/components/parameters/AppIdPath'
        example: example-value
      - $ref: '#/components/parameters/LimitQuery'
        example: example-value
      - $ref: '#/components/parameters/AfterQuery'
        example: example-value
      - $ref: '#/components/parameters/ArchivedQuery'
        example: example-value
      responses:
        '200':
          description: Successfully retrieved action definitions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionDefinitionCollection'
              examples:
                ActionDefinitionCollectionSuccessExample:
                  $ref: '#/components/examples/ActionDefinitionCollectionSuccessExample'
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Listactiondefinitions400Example:
                  summary: Default listActionDefinitions 400 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Listactiondefinitions401Example:
                  summary: Default listActionDefinitions 401 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

              examples:
                Listactiondefinitions500Example:
                  summary: Default listActionDefinitions 500 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
    post:
      tags:
      - Action Definitions
      summary: Hubspot Create an Action Definition
      description: |
        Creates a new custom workflow action definition for the specified application. 
        The action definition includes input fields, output fields, labels, and configuration 
        for how the action appears in the HubSpot workflow editor.
      operationId: createActionDefinition
      x-microcks-operation:
        delay: 100
        dispatcher: SCRIPT
        dispatcherRules: |
          def response = mockRequest.requestContent
          return "ActionDefinitionSuccessExample"
      security:
      - oauth2:
        - automation
      - privateApp: []
      parameters:
      - $ref: '#/components/parameters/AppIdPath'
        example: example-value
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionDefinitionInput'
            examples:
              ActionDefinitionInputExample:
                $ref: '#/components/examples/ActionDefinitionInputExample'
      responses:
        '201':
          description: Successfully created action definition
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionDefinition'
              examples:
                ActionDefinitionSuccessExample:
                  $ref: '#/components/examples/ActionDefinitionSuccessExample'
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Createactiondefinition400Example:
                  summary: Default createActionDefinition 400 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Createactiondefinition401Example:
                  summary: Default createActionDefinition 401 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

              examples:
                Createactiondefinition500Example:
                  summary: Default createActionDefinition 500 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
  /automation/v4/actions/{appId}/{definitionId}:
    get:
      tags:
      - Action Definitions
      summary: Hubspot Retrieve an Action Definition
      description: |
        Retrieves a specific custom action definition by its ID. Returns the complete 
        action definition including all input fields, output fields, and configuration.
      operationId: getActionDefinitionById
      x-microcks-operation:
        delay: 100
        dispatcher: SCRIPT
        dispatcherRules: |
          def response = mockRequest.requestContent
          return "ActionDefinitionSuccessExample"
      security:
      - oauth2:
        - automation
      - privateApp: []
      parameters:
      - $ref: '#/components/parameters/AppIdPath'
        example: example-value
      - $ref: '#/components/parameters/DefinitionIdPath'
        example: example-value
      - $ref: '#/components/parameters/ArchivedQuery'
        example: example-value
      responses:
        '200':
          description: Successfully retrieved action definition
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionDefinition'
              examples:
                ActionDefinitionSuccessExample:
                  $ref: '#/components/examples/ActionDefinitionSuccessExample'
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Getactiondefinitionbyid400Example:
                  summary: Default getActionDefinitionById 400 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Getactiondefinitionbyid401Example:
                  summary: Default getActionDefinitionById 401 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
        '404':
          description: Action definition not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Getactiondefinitionbyid404Example:
                  summary: Default getActionDefinitionById 404 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

              examples:
                Getactiondefinitionbyid500Example:
                  summary: Default getActionDefinitionById 500 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
    patch:
      tags:
      - Action Definitions
      summary: Hubspot Update an Action Definition
      description: |
        Updates an existing custom action definition with the provided changes. 
        Only the specified fields will be updated; other fields remain unchanged.
      operationId: updateActionDefinitionById
      x-microcks-operation:
        delay: 100
        dispatcher: SCRIPT
        dispatcherRules: |
          def response = mockRequest.requestContent
          return "ActionDefinitionSuccessExample"
      security:
      - oauth2:
        - automation
      - privateApp: []
      parameters:
      - $ref: '#/components/parameters/AppIdPath'
        example: example-value
      - $ref: '#/components/parameters/DefinitionIdPath'
        example: example-value
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionDefinitionPatch'
            examples:
              ActionDefinitionPatchExample:
                $ref: '#/components/examples/ActionDefinitionPatchExample'
      responses:
        '200':
          description: Successfully updated action definition
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionDefinition'
              examples:
                ActionDefinitionSuccessExample:
                  $ref: '#/components/examples/ActionDefinitionSuccessExample'
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Updateactiondefinitionbyid400Example:
                  summary: Default updateActionDefinitionById 400 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Updateactiondefinitionbyid401Example:
                  summary: Default updateActionDefinitionById 401 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
        '404':
          description: Action definition not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Updateactiondefinitionbyid404Example:
                  summary: Default updateActionDefinitionById 404 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

              examples:
                Updateactiondefinitionbyid500Example:
                  summary: Default updateActionDefinitionById 500 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
    delete:
      tags:
      - Action Definitions
      summary: Hubspot Archive an Action Definition
      description: |
        Archives (soft deletes) a custom action definition. Archived definitions can be 
        restored by updating their archived status. Active workflows using this action 
        will continue to work until modified.
      operationId: archiveActionDefinitionById
      x-microcks-operation:
        delay: 100
        dispatcher: SCRIPT
        dispatcherRules: |
          def response = mockRequest.requestContent
          return "ArchiveActionDefinitionSuccessExample"
      security:
      - oauth2:
        - automation
      - privateApp: []
      parameters:
      - $ref: '#/components/parameters/AppIdPath'
        example: example-value
      - $ref: '#/components/parameters/DefinitionIdPath'
        example: example-value
      responses:
        '204':
          description: Successfully archived action definition
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Archiveactiondefinitionbyid401Example:
                  summary: Default archiveActionDefinitionById 401 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
        '404':
          description: Action definition not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Archiveactiondefinitionbyid404Example:
                  summary: Default archiveActionDefinitionById 404 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

              examples:
                Archiveactiondefinitionbyid500Example:
                  summary: Default archiveActionDefinitionById 500 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
  /automation/v4/actions/{appId}/{definitionId}/functions:
    get:
      tags:
      - Action Functions
      summary: Hubspot List Action Functions
      description: |
        Retrieves all serverless functions associated with a custom action definition. 
        Functions can execute before or after the main action to transform data or 
        perform additional processing.
      operationId: listActionFunctions
      x-microcks-operation:
        delay: 100
        dispatcher: SCRIPT
        dispatcherRules: |
          def response = mockRequest.requestContent
          return "ActionFunctionCollectionSuccessExample"
      security:
      - oauth2:
        - automation
      - privateApp: []
      parameters:
      - $ref: '#/components/parameters/AppIdPath'
        example: example-value
      - $ref: '#/components/parameters/DefinitionIdPath'
        example: example-value
      responses:
        '200':
          description: Successfully retrieved action functions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionFunctionCollection'
              examples:
                ActionFunctionCollectionSuccessExample:
                  $ref: '#/components/examples/ActionFunctionCollectionSuccessExample'
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Listactionfunctions400Example:
                  summary: Default listActionFunctions 400 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Listactionfunctions401Example:
                  summary: Default listActionFunctions 401 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
        '404':
          description: Action definition not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Listactionfunctions404Example:
                  summary: Default listActionFunctions 404 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

              examples:
                Listactionfunctions500Example:
                  summary: Default listActionFunctions 500 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
  /automation/v4/actions/{appId}/{definitionId}/functions/{functionType}:
    get:
      tags:
      - Action Functions
      summary: Hubspot Retrieve Function by Type
      description: |
        Retrieves a function of a specific type for a custom action definition. 
        Function types include PRE_ACTION_EXECUTION and POST_ACTION_EXECUTION.
      operationId: getActionFunctionByType
      x-microcks-operation:
        delay: 100
        dispatcher: SCRIPT
        dispatcherRules: |
          def response = mockRequest.requestContent
          return "ActionFunctionSuccessExample"
      security:
      - oauth2:
        - automation
      - privateApp: []
      parameters:
      - $ref: '#/compon

# --- truncated at 32 KB (85 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hubspot/refs/heads/main/openapi/hubspot-custom-workflow-actions-api-openapi.yml