openapi: 3.1.0
info:
  title: HubSpot Analytics Events Access Tokens Memberships 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: Memberships
  description: Operations for managing list memberships
paths:
  /crm/v3/lists/{listId}/memberships:
    get:
      operationId: getListMemberships
      summary: Hubspot Get List Members
      description: Returns the records that are members of a specific CRM list. For static lists, returns manually added members. For dynamic lists, returns records that currently match the list filters.
      tags:
      - Memberships
      parameters:
      - name: listId
        in: path
        required: true
        description: The ID of the list.
        schema:
          type: string
        example: '500123'
      - 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
      responses:
        '200':
          description: Successful response with list members.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponseMembership'
              examples:
                Getlistmemberships200Example:
                  summary: Default getListMemberships 200 response
                  x-microcks-default: true
                  value:
                    results:
                    - recordId: '500123'
                      addedAt: '2025-03-15T14:30:00Z'
                    paging:
                      next: {}
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /crm/v3/lists/{listId}/memberships/add:
    put:
      operationId: addListMembers
      summary: Hubspot Add Members to a List
      description: Adds records to a static CRM list by their record IDs. This operation is only available for static lists. Records added will remain members until explicitly removed.
      tags:
      - Memberships
      parameters:
      - name: listId
        in: path
        required: true
        description: The ID of the static list to add members to.
        schema:
          type: string
        example: '500123'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MembershipChangeRequest'
            examples:
              AddlistmembersRequestExample:
                summary: Default addListMembers request
                x-microcks-default: true
                value:
                  recordIdsToAdd:
                  - '500123'
                  recordIdsToRemove:
                  - '500123'
      responses:
        '200':
          description: Members added successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipChangeResponse'
              examples:
                Addlistmembers200Example:
                  summary: Default addListMembers 200 response
                  x-microcks-default: true
                  value:
                    recordIdsAdded:
                    - '500123'
                    recordIdsAlreadyMember:
                    - '500123'
                    recordIdsRemoved:
                    - '500123'
                    recordIdsMissing:
                    - '500123'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /crm/v3/lists/{listId}/memberships/remove:
    put:
      operationId: removeListMembers
      summary: Hubspot Remove Members From a List
      description: Removes records from a static CRM list by their record IDs. This operation is only available for static lists. The records themselves will not be deleted, only removed from the list.
      tags:
      - Memberships
      parameters:
      - name: listId
        in: path
        required: true
        description: The ID of the static list to remove members from.
        schema:
          type: string
        example: '500123'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MembershipChangeRequest'
            examples:
              RemovelistmembersRequestExample:
                summary: Default removeListMembers request
                x-microcks-default: true
                value:
                  recordIdsToAdd:
                  - '500123'
                  recordIdsToRemove:
                  - '500123'
      responses:
        '200':
          description: Members removed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipChangeResponse'
              examples:
                Removelistmembers200Example:
                  summary: Default removeListMembers 200 response
                  x-microcks-default: true
                  value:
                    recordIdsAdded:
                    - '500123'
                    recordIdsAlreadyMember:
                    - '500123'
                    recordIdsRemoved:
                    - '500123'
                    recordIdsMissing:
                    - '500123'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Membership:
      type: object
      description: A list membership record.
      properties:
        recordId:
          type: string
          description: The ID of the CRM record that is a member of the list.
          example: '500123'
        addedAt:
          type: string
          format: date-time
          description: The date and time the record was added to the list.
          example: '2025-03-15T14:30:00Z'
    MembershipChangeResponse:
      type: object
      description: Response from a list membership change operation.
      properties:
        recordIdsAdded:
          type: array
          items:
            type: string
          example:
          - '500123'
        recordIdsAlreadyMember:
          type: array
          items:
            type: string
          example:
          - '500123'
        recordIdsRemoved:
          type: array
          items:
            type: string
          example:
          - '500123'
        recordIdsMissing:
          type: array
          items:
            type: string
          example:
          - '500123'
    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
    MembershipChangeRequest:
      type: object
      description: Request body for adding or removing list members.
      properties:
        recordIdsToAdd:
          type: array
          items:
            type: string
          description: The IDs of records to add to the list.
          example:
          - '500123'
        recordIdsToRemove:
          type: array
          items:
            type: string
          description: The IDs of records to remove from the list.
          example:
          - '500123'
    Paging:
      type: object
      description: Pagination information.
      properties:
        next:
          type: object
          properties:
            after:
              type: string
          example:
            after: example-value
    CollectionResponseMembership:
      type: object
      description: A paginated list of list memberships.
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Membership'
          example:
          - recordId: '500123'
            addedAt: '2025-03-15T14:30:00Z'
        paging:
          $ref: '#/components/schemas/Paging'
  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