HubSpot Action Definitions API

openapi: 3.2.0
info:
  title: HubSpot Analytics Events Access Tokens Action Definitions API
  description: "The HubSpot Analytics Events API allows you to retrieve event completion data \nfrom your HubSpot account. Use this API to query event instances associated with \nCRM objects, filter by event types, and analyze user behavior and engagement patterns.\n\n## Key Features\n- Retrieve event instances for CRM objects\n- Filter events by type, date range, and object\n- Paginate through large result sets\n- Query available event types\n"
  version: 3.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 Server
tags:
- name: Action Definitions
  description: Operations to create and manage custom workflow action definitions
paths:
  /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 \napplication. Use query parameters to filter by archived status and control pagination.\n"
      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:
                    - message: This is an example description.
                      code: example-value
                      in: example-value
                      subCategory: standard
                      context:
                        key: value
                    context:
                      key: value
                    links:
                      key: value
        '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:
                    - message: This is an example description.
                      code: example-value
                      in: example-value
                      subCategory: standard
                      context:
                        key: value
                    context:
                      key: value
                    links:
                      key: value
        '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:
                    - message: This is an example description.
                      code: example-value
                      in: example-value
                      subCategory: standard
                      context:
                        key: value
                    context:
                      key: value
                    links:
                      key: value
    post:
      tags:
      - Action Definitions
      summary: Hubspot Create an Action Definition
      description: "Creates a new custom workflow action definition for the specified application. \nThe action definition includes input fields, output fields, labels, and configuration \nfor how the action appears in the HubSpot workflow editor.\n"
      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:
                    - message: This is an example description.
                      code: example-value
                      in: example-value
                      subCategory: standard
                      context:
                        key: value
                    context:
                      key: value
                    links:
                      key: value
        '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:
                    - message: This is an example description.
                      code: example-value
                      in: example-value
                      subCategory: standard
                      context:
                        key: value
                    context:
                      key: value
                    links:
                      key: value
        '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:
                    - message: This is an example description.
                      code: example-value
                      in: example-value
                      subCategory: standard
                      context:
                        key: value
                    context:
                      key: value
                    links:
                      key: value
  /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 \naction definition including all input fields, output fields, and configuration.\n"
      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:
                    - message: This is an example description.
                      code: example-value
                      in: example-value
                      subCategory: standard
                      context:
                        key: value
                    context:
                      key: value
                    links:
                      key: value
        '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:
                    - message: This is an example description.
                      code: example-value
                      in: example-value
                      subCategory: standard
                      context:
                        key: value
                    context:
                      key: value
                    links:
                      key: value
        '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:
                    - message: This is an example description.
                      code: example-value
                      in: example-value
                      subCategory: standard
                      context:
                        key: value
                    context:
                      key: value
                    links:
                      key: value
        '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:
                    - message: This is an example description.
                      code: example-value
                      in: example-value
                      subCategory: standard
                      context:
                        key: value
                    context:
                      key: value
                    links:
                      key: value
    patch:
      tags:
      - Action Definitions
      summary: Hubspot Update an Action Definition
      description: "Updates an existing custom action definition with the provided changes. \nOnly the specified fields will be updated; other fields remain unchanged.\n"
      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:
                    - message: This is an example description.
                      code: example-value
                      in: example-value
                      subCategory: standard
                      context:
                        key: value
                    context:
                      key: value
                    links:
                      key: value
        '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:
                    - message: This is an example description.
                      code: example-value
                      in: example-value
                      subCategory: standard
                      context:
                        key: value
                    context:
                      key: value
                    links:
                      key: value
        '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:
                    - message: This is an example description.
                      code: example-value
                      in: example-value
                      subCategory: standard
                      context:
                        key: value
                    context:
                      key: value
                    links:
                      key: value
        '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:
                    - message: This is an example description.
                      code: example-value
                      in: example-value
                      subCategory: standard
                      context:
                        key: value
                    context:
                      key: value
                    links:
                      key: value
    delete:
      tags:
      - Action Definitions
      summary: Hubspot Archive an Action Definition
      description: "Archives (soft deletes) a custom action definition. Archived definitions can be \nrestored by updating their archived status. Active workflows using this action \nwill continue to work until modified.\n"
      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:
                    - message: This is an example description.
                      code: example-value
                      in: example-value
                      subCategory: standard
                      context:
                        key: value
                    context:
                      key: value
                    links:
                      key: value
        '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:
                    - message: This is an example description.
                      code: example-value
                      in: example-value
                      subCategory: standard
                      context:
                        key: value
                    context:
                      key: value
                    links:
                      key: value
        '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:
                    - message: This is an example description.
                      code: example-value
                      in: example-value
                      subCategory: standard
                      context:
                        key: value
                    context:
                      key: value
                    links:
                      key: value
components:
  parameters:
    LimitQuery:
      name: limit
      in: query
      description: Maximum number of results to return per page
      schema:
        type: integer
        default: 100
        maximum: 500
      example: 100
    AppIdPath:
      name: appId
      in: path
      required: true
      description: The unique identifier of the HubSpot application
      schema:
        type: integer
        format: int32
      example: 12345
    DefinitionIdPath:
      name: definitionId
      in: path
      required: true
      description: The unique identifier of the action definition
      schema:
        type: string
      example: action-def-001
    AfterQuery:
      name: after
      in: query
      description: Pagination cursor for the next page of results
      schema:
        type: string
      example: NTI1Cg%3D%3D
    ArchivedQuery:
      name: archived
      in: query
      description: Whether to include archived action definitions
      schema:
        type: boolean
        default: false
      example: false
  schemas:
    ActionFunctionReference:
      type: object
      description: A reference to a function associated with an action
      required:
      - functionType
      - id
      properties:
        functionType:
          type: string
          enum:
          - PRE_ACTION_EXECUTION
          - PRE_FETCH_OPTIONS
          - POST_FETCH_OPTIONS
          - POST_ACTION_EXECUTION
          description: The type of function
          example: PRE_ACTION_EXECUTION
        id:
          type: string
          description: The unique identifier of the function
          example: '500123'
    FieldOption:
      type: object
      description: An option for an enumeration field
      required:
      - label
      - value
      properties:
        label:
          type: string
          description: Display label for the option
          example: Example Record
        value:
          type: string
          description: The value of the option
          example: example-value
        displayOrder:
          type: integer
          description: Order in which to display the option
          example: 100
    Error:
      type: object
      description: An error response
      required:
      - category
      - correlationId
      - message
      properties:
        category:
          type: string
          description: The error category
          example: standard
        correlationId:
          type: string
          format: uuid
          description: A unique identifier for this error instance
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        message:
          type: string
          description: A human-readable error message
          example: This is an example description.
        subCategory:
          type: string
          description: A more specific error category
          example: standard
        errors:
          type: array
          description: Detailed error information
          items:
            $ref: '#/components/schemas/ErrorDetail'
          example:
          - message: This is an example description.
            code: example-value
            in: example-value
            subCategory: standard
            context:
              key: value
        context:
          type: object
          description: Additional context about the error
          additionalProperties:
            type: array
            items:
              type: string
          example:
            key: value
        links:
          type: object
          description: Related links
          additionalProperties:
            type: string
          example:
            key: value
    ActionDefinitionInput:
      type: object
      description: Input for creating a new action definition
      required:
      - actionUrl
      - labels
      - objectTypes
      properties:
        actionUrl:
          type: string
          format: uri
          description: The URL that HubSpot will call when the action executes
          example: https://app.hubspot.com/contacts/12345
        labels:
          $ref: '#/components/schemas/ActionLabels'
        inputFields:
          type: array
          description: Input fields for the action
          items:
            $ref: '#/components/schemas/InputField'
          example:
          - typeDefinition: {}
            supportedValueTypes:
            - {}
            isRequired: true
        outputFields:
          type: array
          description: Output fields for the action
          items:
            $ref: '#/components/schemas/OutputField'
          example:
          - typeDefinition: {}
        objectTypes:
          type: array
          description: CRM object types this action can operate on
          items:
            type: string
            enum:
            - CONTACT
            - COMPANY
            - DEAL
            - TICKET
            - QUOTE
          example:
          - CONTACT
        objectRequestOptions:
          $ref: '#/components/schemas/ObjectRequestOptions'
        published:
          type: boolean
          description: Whether to publish the action immediately
          example: true
    InputField:
      type: object
      description: An input field for the action
      required:
      - typeDefinition
      - supportedValueTypes
      properties:
        typeDefinition:
          $ref: '#/components/schemas/FieldTypeDefinition'
        supportedValueTypes:
          type: array
          description: The types of values that can be provided for this field
          items:
            type: string
            enum:
            - STATIC_VALUE
            - OBJECT_PROPERTY
            - OUTPUT_FROM_PREVIOUS_ACTION
          example:
          - STATIC_VALUE
        isRequired:
          type: boolean
          description: Whether this field is required
          example: true
    ActionDefinitionCollection:
      type: object
      description: A paginated collection of action definitions
      required:
      - results
      properties:
        results:
          type: array
          description: List of action definitions
          items:
            $ref: '#/components/schemas/ActionDefinition'
          example:
          - id: '500123'
            revisionId: '500123'
            actionUrl: https://app.hubspot.com/contacts/12345
            labels: {}
            inputFields:
            - typeDefinition: {}
              supportedValueTypes:
              - {}
              isRequired: true
            outputFields:
            - typeDefinition: {}
            objectTypes:
            - CONTACT
            objectRequestOptions: {}
            published: true
            functions:
            - functionType: PRE_ACTION_EXECUTION
              id: '500123'
        paging:
          $ref: '#/components/schemas/Paging'
    OutputField:
      type: object
      description: An output field returned by the action
      required:
      - typeDefinition
      properties:
        typeDefinition:
          $ref: '#/components/schemas/FieldTypeDefinition'
    Paging:
      type: object
      description: Pagination information
      properties:
        next:
          type: object
          properties:
            after:
              type: string
              description: Cursor for the next page
          example:
            after: example-value
    ActionDefinition:
      type: object
      description: A custom workflow action definition
      required:
      - id
      - revisionId
      - actionUrl
      - labels
      - objectTypes
      properties:
        id:
          type: string
          description: The unique identifier of the action definition
          example: '5001

# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hubspot/refs/heads/main/openapi/hubspot-action-definitions-api-openapi.yml