openapi: 3.1.0
info:
  title: HubSpot Analytics Events Access Tokens Lists 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: Lists
  description: Operations for managing CRM lists
paths:
  /crm/v3/lists:
    get:
      operationId: listLists
      summary: Hubspot List All Lists
      description: Returns a page of all CRM lists in the portal. Lists can be either static (manually managed membership) or dynamic (filter-based membership). Use the limit and after parameters to paginate results.
      tags:
      - Lists
      parameters:
      - name: limit
        in: query
        description: The maximum number of results to return per page.
        schema:
          type: integer
          default: 20
          maximum: 500
        example: 20
      - name: after
        in: query
        description: The cursor for pagination to get the next page of results.
        schema:
          type: string
        example: example-value
      - name: objectTypeId
        in: query
        description: The object type ID to filter lists by (e.g., 0-1 for contacts).
        schema:
          type: string
        example: '500123'
      - name: listType
        in: query
        description: Filter by list type - STATIC or DYNAMIC.
        schema:
          type: string
          enum:
          - STATIC
          - DYNAMIC
        example: STATIC
      responses:
        '200':
          description: Successful response with a list of CRM lists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponseList'
              examples:
                Listlists200Example:
                  summary: Default listLists 200 response
                  x-microcks-default: true
                  value:
                    results:
                    - listId: '500123'
                      name: Example Record
                      listType: STATIC
                      objectTypeId: '500123'
                      processingStatus: active
                      createdAt: '2025-03-15T14:30:00Z'
                      updatedAt: '2025-03-15T14:30:00Z'
                      filterBranch: {}
                      memberCount: 10
                    paging:
                      next: {}
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createList
      summary: Hubspot Create a List
      description: Creates a new CRM list. You can create either a static list with manually managed membership or a dynamic list with filter-based membership that updates automatically as records match the criteria.
      tags:
      - Lists
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListCreateRequest'
            examples:
              CreatelistRequestExample:
                summary: Default createList request
                x-microcks-default: true
                value:
                  name: Example Record
                  objectTypeId: '500123'
                  processingType: MANUAL
                  filterBranch: {}
      responses:
        '200':
          description: List created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List'
              examples:
                Createlist200Example:
                  summary: Default createList 200 response
                  x-microcks-default: true
                  value:
                    listId: '500123'
                    name: Example Record
                    listType: STATIC
                    objectTypeId: '500123'
                    processingStatus: active
                    createdAt: '2025-03-15T14:30:00Z'
                    updatedAt: '2025-03-15T14:30:00Z'
                    filterBranch: {}
                    memberCount: 10
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /crm/v3/lists/{listId}:
    get:
      operationId: getList
      summary: Hubspot Get a List
      description: Returns details of a specific CRM list by its ID, including membership type, filter definitions for dynamic lists, and metadata.
      tags:
      - Lists
      parameters:
      - name: listId
        in: path
        required: true
        description: The ID of the list to retrieve.
        schema:
          type: string
        example: '500123'
      responses:
        '200':
          description: Successful response with the list details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List'
              examples:
                Getlist200Example:
                  summary: Default getList 200 response
                  x-microcks-default: true
                  value:
                    listId: '500123'
                    name: Example Record
                    listType: STATIC
                    objectTypeId: '500123'
                    processingStatus: active
                    createdAt: '2025-03-15T14:30:00Z'
                    updatedAt: '2025-03-15T14:30:00Z'
                    filterBranch: {}
                    memberCount: 10
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteList
      summary: Hubspot Delete a List
      description: Permanently deletes a CRM list by its ID. This removes the list definition but does not delete the CRM records that were members of the list.
      tags:
      - Lists
      parameters:
      - name: listId
        in: path
        required: true
        description: The ID of the list to delete.
        schema:
          type: string
        example: '500123'
      responses:
        '204':
          description: List deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    List:
      type: object
      description: A HubSpot CRM list.
      properties:
        listId:
          type: string
          description: The unique identifier for the list.
          example: '500123'
        name:
          type: string
          description: The name of the list.
          example: Example Record
        listType:
          type: string
          enum:
          - STATIC
          - DYNAMIC
          description: Whether the list is static (manually managed) or dynamic (filter-based).
          example: STATIC
        objectTypeId:
          type: string
          description: The object type the list contains (e.g., 0-1 for contacts).
          example: '500123'
        processingStatus:
          type: string
          description: The current processing status of the list.
          example: active
        createdAt:
          type: string
          format: date-time
          description: The date and time the list was created.
          example: '2025-03-15T14:30:00Z'
        updatedAt:
          type: string
          format: date-time
          description: The date and time the list was last updated.
          example: '2025-03-15T14:30:00Z'
        filterBranch:
          type: object
          description: The filter definition for dynamic lists.
          example: {}
        memberCount:
          type: integer
          description: The current number of members in the list.
          example: 10
    CollectionResponseList:
      type: object
      description: A paginated list of CRM lists.
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/List'
          example:
          - listId: '500123'
            name: Example Record
            listType: STATIC
            objectTypeId: '500123'
            processingStatus: active
            createdAt: '2025-03-15T14:30:00Z'
            updatedAt: '2025-03-15T14:30:00Z'
            filterBranch: {}
            memberCount: 10
        paging:
          $ref: '#/components/schemas/Paging'
    Error:
      type: object
      description: An error response.
      properties:
        status:
          type: string
          example: active
        message:
          type: string
          example: This is an example description.
        correlationId:
          type: string
          example: '500123'
        category:
          type: string
          example: standard
    ListCreateRequest:
      type: object
      description: Request body for creating a new CRM list.
      required:
      - name
      - objectTypeId
      - processingType
      properties:
        name:
          type: string
          description: The name of the list.
          example: Example Record
        objectTypeId:
          type: string
          description: The object type ID for the list (e.g., 0-1 for contacts).
          example: '500123'
        processingType:
          type: string
          enum:
          - MANUAL
          - DYNAMIC
          - SNAPSHOT
          description: The type of list processing.
          example: MANUAL
        filterBranch:
          type: object
          description: The filter branch definition for dynamic lists.
          example: {}
    Paging:
      type: object
      description: Pagination information.
      properties:
        next:
          type: object
          properties:
            after:
              type: string
          example:
            after: example-value
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request is invalid or missing required parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  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