HubSpot Batch Portal Operations API

openapi: 3.1.0
info:
  title: HubSpot Analytics Events Access Tokens Batch Portal Operations 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: Batch Portal Operations
  description: Perform bulk operations on portal flag states
paths:
  /feature-flags/v3/{appId}/flags/{flagName}/portals/batch/upsert:
    post:
      tags:
      - Batch Portal Operations
      summary: Hubspot Batch Create or Update Portal Flag States
      description: 'Sets flag states for multiple portals (accounts) in a single request.

        Efficiently enables or disables features for multiple accounts at once.

        '
      operationId: batchUpsertPortalFlagStates
      x-microcks-operation:
        delay: 150
        dispatcher: SCRIPT
        dispatcherRules: 'def mockResponse = mockRequest.getResponseByDispatchCriteria("BatchPortalFlagStateResponseExample")

          return "BatchPortalFlagStateResponseExample"

          '
      security:
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/AppIdPath'
        example: example-value
      - $ref: '#/components/parameters/FlagNamePath'
        example: example-value
      requestBody:
        required: true
        description: List of portal flag states to create or update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchPortalFlagStateInput'
            examples:
              BatchPortalFlagStateInputExample:
                $ref: '#/components/examples/BatchPortalFlagStateInputExample'
      responses:
        '200':
          description: Successfully processed all batch portal flag state updates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchPortalFlagStateResponse'
              examples:
                BatchPortalFlagStateResponseExample:
                  $ref: '#/components/examples/BatchPortalFlagStateResponseExample'
        '207':
          description: Multi-status - Some operations succeeded while others failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchPortalFlagStateResponseWithErrors'
              examples:
                BatchPortalFlagStateResponseWithErrorsExample:
                  $ref: '#/components/examples/BatchPortalFlagStateResponseWithErrorsExample'
        '400':
          description: Bad request - Invalid parameters provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Batchupsertportalflagstates400Example:
                  summary: Default batchUpsertPortalFlagStates 400 response
                  x-microcks-default: true
                  value:
                    category: VALIDATION_ERROR
                    correlationId: aeb5f871-7f07-4993-9211-075dc63e7cbf
                    message: Invalid input JSON
                    subCategory: INVALID_PARAMETER
                    context: &id001
                      key: value
                    links: &id002
                      key: value
                    errors: &id003
                    - message: flagState is required
                      code: REQUIRED_FIELD
                      subCategory: MISSING_FIELD
                      in: body
                      context:
                        key: value
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Batchupsertportalflagstates401Example:
                  summary: Default batchUpsertPortalFlagStates 401 response
                  x-microcks-default: true
                  value:
                    category: VALIDATION_ERROR
                    correlationId: aeb5f871-7f07-4993-9211-075dc63e7cbf
                    message: Invalid input JSON
                    subCategory: INVALID_PARAMETER
                    context: *id001
                    links: *id002
                    errors: *id003
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Batchupsertportalflagstates500Example:
                  summary: Default batchUpsertPortalFlagStates 500 response
                  x-microcks-default: true
                  value:
                    category: VALIDATION_ERROR
                    correlationId: aeb5f871-7f07-4993-9211-075dc63e7cbf
                    message: Invalid input JSON
                    subCategory: INVALID_PARAMETER
                    context: *id001
                    links: *id002
                    errors: *id003
  /feature-flags/v3/{appId}/flags/{flagName}/portals/batch/delete:
    post:
      tags:
      - Batch Portal Operations
      summary: Hubspot Batch Delete Portal Flag States
      description: 'Removes flag state overrides for multiple portals (accounts) in a single request.

        All specified portals will revert to using the application-level default flag state.

        '
      operationId: batchDeletePortalFlagStates
      x-microcks-operation:
        delay: 150
        dispatcher: SCRIPT
        dispatcherRules: 'def mockResponse = mockRequest.getResponseByDispatchCriteria("BatchPortalFlagStateResponseExample")

          return "BatchPortalFlagStateResponseExample"

          '
      security:
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/AppIdPath'
        example: example-value
      - $ref: '#/components/parameters/FlagNamePath'
        example: example-value
      requestBody:
        required: true
        description: List of portal IDs to delete flag states for
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchDeleteInput'
            examples:
              BatchDeleteInputExample:
                $ref: '#/components/examples/BatchDeleteInputExample'
      responses:
        '200':
          description: Successfully deleted all batch portal flag states
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchPortalFlagStateResponse'
              examples:
                BatchPortalFlagStateResponseExample:
                  $ref: '#/components/examples/BatchPortalFlagStateResponseExample'
        '207':
          description: Multi-status - Some operations succeeded while others failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchPortalFlagStateResponseWithErrors'
              examples:
                BatchPortalFlagStateResponseWithErrorsExample:
                  $ref: '#/components/examples/BatchPortalFlagStateResponseWithErrorsExample'
        '400':
          description: Bad request - Invalid parameters provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Batchdeleteportalflagstates400Example:
                  summary: Default batchDeletePortalFlagStates 400 response
                  x-microcks-default: true
                  value:
                    category: VALIDATION_ERROR
                    correlationId: aeb5f871-7f07-4993-9211-075dc63e7cbf
                    message: Invalid input JSON
                    subCategory: INVALID_PARAMETER
                    context: &id004
                      key: value
                    links: &id005
                      key: value
                    errors: &id006
                    - message: flagState is required
                      code: REQUIRED_FIELD
                      subCategory: MISSING_FIELD
                      in: body
                      context:
                        key: value
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Batchdeleteportalflagstates401Example:
                  summary: Default batchDeletePortalFlagStates 401 response
                  x-microcks-default: true
                  value:
                    category: VALIDATION_ERROR
                    correlationId: aeb5f871-7f07-4993-9211-075dc63e7cbf
                    message: Invalid input JSON
                    subCategory: INVALID_PARAMETER
                    context: *id004
                    links: *id005
                    errors: *id006
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Batchdeleteportalflagstates500Example:
                  summary: Default batchDeletePortalFlagStates 500 response
                  x-microcks-default: true
                  value:
                    category: VALIDATION_ERROR
                    correlationId: aeb5f871-7f07-4993-9211-075dc63e7cbf
                    message: Invalid input JSON
                    subCategory: INVALID_PARAMETER
                    context: *id004
                    links: *id005
                    errors: *id006
components:
  examples:
    BatchPortalFlagStateResponseWithErrorsExample:
      summary: Example batch response with errors
      value:
        status: COMPLETE
        results:
        - appId: 12345678
          flagName: new-dashboard-feature
          portalId: 98765432
          flagState: 'ON'
        errors:
        - status: error
          category: VALIDATION_ERROR
          message: 'Invalid portal ID: 99999999'
          context:
            portalId:
            - '99999999'
        startedAt: '2024-01-15T10:30:00Z'
        completedAt: '2024-01-15T10:30:01Z'
    BatchDeleteInputExample:
      summary: Example batch delete input
      value:
        inputs:
        - portalId: 98765432
        - portalId: 87654321
    BatchPortalFlagStateInputExample:
      summary: Example batch portal flag state input
      value:
        inputs:
        - portalId: 98765432
          flagState: 'ON'
        - portalId: 87654321
          flagState: 'OFF'
    BatchPortalFlagStateResponseExample:
      summary: Example successful batch response
      value:
        status: COMPLETE
        results:
        - appId: 12345678
          flagName: new-dashboard-feature
          portalId: 98765432
          flagState: 'ON'
        - appId: 12345678
          flagName: new-dashboard-feature
          portalId: 87654321
          flagState: 'OFF'
        startedAt: '2024-01-15T10:30:00Z'
        completedAt: '2024-01-15T10:30:01Z'
  parameters:
    AppIdPath:
      name: appId
      in: path
      required: true
      description: The unique identifier for the HubSpot application
      schema:
        type: integer
        format: int64
      example: 12345678
    FlagNamePath:
      name: flagName
      in: path
      required: true
      description: The name of the feature flag
      schema:
        type: string
      example: new-dashboard-feature
  schemas:
    ErrorDetail:
      type: object
      description: Detailed error information for specific validation failures
      required:
      - message
      properties:
        message:
          type: string
          description: Specific error message
          example: flagState is required
        code:
          type: string
          description: Error code
          example: REQUIRED_FIELD
        subCategory:
          type: string
          description: Error sub-category
          example: MISSING_FIELD
        in:
          type: string
          description: Location of the error (e.g., path, body, query)
          example: body
        context:
          type: object
          description: Additional context for the error
          additionalProperties:
            type: array
            items:
              type: string
          example:
            key: value
    FlagState:
      type: string
      description: The state of a feature flag
      enum:
      - 'ON'
      - 'OFF'
      - ABSENT
      example: 'ON'
    BatchDeleteInput:
      type: object
      description: Input payload for batch deleting portal flag states
      required:
      - inputs
      properties:
        inputs:
          type: array
          description: List of portal IDs to delete flag states for
          items:
            $ref: '#/components/schemas/BatchDeleteInputItem'
          example:
          - portalId: 98765432
    BatchError:
      type: object
      description: Represents an error that occurred for a specific item in a batch operation
      required:
      - status
      - category
      - message
      properties:
        status:
          type: string
          description: Error status code
          example: error
        category:
          type: string
          description: Error category
          example: VALIDATION_ERROR
        message:
          type: string
          description: Human-readable error message
          example: Invalid portal ID
        context:
          type: object
          description: Additional context about the error
          additionalProperties:
            type: array
            items:
              type: string
          example:
            key: value
    Error:
      type: object
      description: Represents an error response from the API
      required:
      - category
      - correlationId
      - message
      properties:
        category:
          type: string
          description: The error category
          example: VALIDATION_ERROR
        correlationId:
          type: string
          format: uuid
          description: Unique identifier for the request, useful for debugging
          example: aeb5f871-7f07-4993-9211-075dc63e7cbf
        message:
          type: string
          description: Human-readable error message
          example: Invalid input JSON
        subCategory:
          type: string
          description: More specific error classification
          example: INVALID_PARAMETER
        context:
          type: object
          description: Additional context about the error
          additionalProperties:
            type: array
            items:
              type: string
          example:
            key: value
        links:
          type: object
          description: Helpful links related to the error
          additionalProperties:
            type: string
          example:
            key: value
        errors:
          type: array
          description: List of detailed error information
          items:
            $ref: '#/components/schemas/ErrorDetail'
          example:
          - message: flagState is required
            code: REQUIRED_FIELD
            subCategory: MISSING_FIELD
            in: body
            context:
              key: value
    BatchPortalFlagStateResponseWithErrors:
      type: object
      description: Response for batch operations that had some failures
      required:
      - status
      - results
      properties:
        status:
          type: string
          description: The overall status of the batch operation
          enum:
          - COMPLETE
          - PENDING
          example: COMPLETE
        results:
          type: array
          description: List of portal flag states that were successfully affected
          items:
            $ref: '#/components/schemas/PortalFlagState'
          example:
          - appId: 12345678
            flagName: new-dashboard-feature
            portalId: 98765432
            flagState: {}
        errors:
          type: array
          description: List of errors that occurred during the batch operation
          items:
            $ref: '#/components/schemas/BatchError'
          example:
          - status: error
            category: VALIDATION_ERROR
            message: Invalid portal ID
            context:
              key: value
        startedAt:
          type: string
          format: date-time
          description: Timestamp when the batch operation started
          example: '2025-03-15T14:30:00Z'
        completedAt:
          type: string
          format: date-time
          description: Timestamp when the batch operation completed
          example: '2025-03-15T14:30:00Z'
    BatchPortalFlagStateResponse:
      type: object
      description: Response for successful batch portal flag state operations
      required:
      - status
      - results
      properties:
        status:
          type: string
          description: The overall status of the batch operation
          enum:
          - COMPLETE
          - PENDING
          example: COMPLETE
        results:
          type: array
          description: List of portal flag states that were successfully affected
          items:
            $ref: '#/components/schemas/PortalFlagState'
          example:
          - appId: 12345678
            flagName: new-dashboard-feature
            portalId: 98765432
            flagState: {}
        startedAt:
          type: string
          format: date-time
          description: Timestamp when the batch operation started
          example: '2024-01-15T10:30:00Z'
        completedAt:
          type: string
          format: date-time
          description: Timestamp when the batch operation completed
          example: '2024-01-15T10:30:01Z'
    PortalFlagState:
      type: object
      description: Represents the flag state override for a specific portal (account)
      required:
      - appId
      - flagName
      - portalId
      - flagState
      properties:
        appId:
          type: integer
          format: int64
          description: The unique identifier for the HubSpot application
          example: 12345678
        flagName:
          type: string
          description: The name of the feature flag
          example: new-dashboard-feature
        portalId:
          type: integer
          format: int64
          description: The unique identifier for the HubSpot portal (account)
          example: 98765432
        flagState:
          $ref: '#/components/schemas/FlagState'
    BatchPortalFlagStateInputItem:
      type: object
      description: Individual item in a batch upsert request
      required:
      - portalId
      - flagState
      properties:
        portalId:
          type: integer
          format: int64
          description: The unique identifier for the HubSpot portal (account)
          example: 98765432
        flagState:
          $ref: '#/components/schemas/FlagState'
    BatchDeleteInputItem:
      type: object
      description: Individual item in a batch delete request
      required:
      - portalId
      properties:
        portalId:
          type: integer
          format: int64
          description: The unique identifier for the HubSpot portal (account)
          example: 98765432
    BatchPortalFlagStateInput:
      type: object
      description: Input payload for batch creating or updating portal flag states
      required:
      - inputs
      properties:
        inputs:
          type: array
          description: List of portal flag state inputs
          items:
            $ref: '#/components/schemas/BatchPortalFlagStateInputItem'
          example:
          - portalId: 98765432
            flagState: {}
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.hubspot.com/oauth/authorize
          tokenUrl: https://api.hubapi.com/oauth/v1/token
          scopes:
            analytics.read: Read analytics data