openapi: 3.0.1
info:
  title: HubSpot Settings Teams
  description: Basepom for all HubSpot Projects
  version: 2026-09
  x-hubspot-product-tier-requirements:
    marketing: FREE
    sales: FREE
    service: FREE
    cms: FREE
    commerce: FREE
    crmHub: FREE
    dataHub: FREE
servers:
- url: https://api.hubapi.com
tags:
- name: Basic
- name: Batch
paths:
  /settings/teams/2026-09:
    get:
      tags:
      - Basic
      summary: List teams
      description: Retrieve a list of teams from your HubSpot account. This endpoint allows you to paginate
        through the teams using the 'limit' and 'after' query parameters. It is useful for obtaining an
        overview of all teams configured in the account.
      operationId: get-/settings/teams/2026-09
      parameters:
      - name: after
        in: query
        description: The paging cursor token of the last successfully read resource will be returned as
          the `paging.next.after` JSON property of a paged response containing more results.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: limit
        in: query
        description: The maximum number of results to display per page.
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponseTeamResponseForwardPaging'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - settings.users.teams.read
    post:
      tags:
      - Basic
      summary: Create Team
      description: Create a new team in your HubSpot account. This endpoint allows you to define the team's
        name, parent team, and members. The request body must include the team's name and members. Upon
        successful creation, the response will include the URL of the newly created team resource.
      operationId: post-/settings/teams/2026-09
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TeamCreateRequest'
        required: true
      responses:
        '201':
          description: successful operation
          headers:
            Location:
              description: URL of the newly created resource
              style: simple
              explode: false
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamResponse'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - settings.users.teams.write
  /settings/teams/2026-09/{teamId}:
    get:
      tags:
      - Basic
      summary: Retrieve team
      description: Retrieve detailed information about a specific team in your HubSpot account using the
        team's unique identifier. This endpoint is useful for accessing the team's properties, such as
        its name and parent team ID, to manage or display team-related data.
      operationId: get-/settings/teams/2026-09/{teamId}
      parameters:
      - name: teamId
        in: path
        description: The unique identifier of the team to retrieve.
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamResponse'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - settings.users.teams.read
    delete:
      tags:
      - Basic
      summary: Delete team
      description: Delete a specific team from your HubSpot account using the team's unique identifier.
        This operation will remove the team and its associated data. Ensure that you have the necessary
        permissions to perform this action.
      operationId: delete-/settings/teams/2026-09/{teamId}
      parameters:
      - name: teamId
        in: path
        description: The unique identifier of the team to delete.
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '204':
          description: No content
          content: {}
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - settings.users.teams.write
    patch:
      tags:
      - Basic
      summary: Update team
      description: Update the details of a specific team in your HubSpot account. This endpoint allows
        you to modify the team's information, such as its name or parent team ID. Ensure that the teamId
        provided in the path is correct, as it identifies the team to be updated.
      operationId: patch-/settings/teams/2026-09/{teamId}
      parameters:
      - name: teamId
        in: path
        description: The unique identifier of the team to update.
        required: true
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TeamUpdateRequest'
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamResponse'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - settings.users.teams.write
  /settings/teams/2026-09/{teamId}/members:
    get:
      tags:
      - Basic
      summary: List members
      description: Retrieve a list of members for a specified team in your HubSpot account. This endpoint
        allows you to paginate through the team members using the 'limit' and 'after' query parameters.
        It is useful for managing and viewing team compositions and roles within your organization.
      operationId: get-/settings/teams/2026-09/{teamId}/members
      parameters:
      - name: teamId
        in: path
        description: The unique identifier of the team whose members are being retrieved.
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: after
        in: query
        description: The paging cursor token of the last successfully read resource, returned as the `paging.next.after`
          JSON property of a paged response containing more results.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: limit
        in: query
        description: The maximum number of results to display per page.
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponseTeamMemberResponseForwardPaging'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - settings.users.teams.read
    post:
      tags:
      - Basic
      summary: Add Team Members
      description: Assign new members to a specific team in your HubSpot account. This endpoint allows
        you to add users to a team by specifying their user IDs and roles. It is useful for managing team
        compositions and ensuring the right users have access to team resources.
      operationId: post-/settings/teams/2026-09/{teamId}/members
      parameters:
      - name: teamId
        in: path
        description: The unique identifier of the team to which members will be added.
        required: true
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TeamMemberAssignment'
        required: true
      responses:
        '201':
          description: successful operation
          headers:
            Location:
              description: URL of the newly created resource
              style: simple
              explode: false
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamMemberResponse'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - settings.users.teams.write
  /settings/teams/2026-09/{teamId}/members/batch:
    post:
      tags:
      - Batch
      summary: Batch assign members
      description: Assign multiple members to a specific team in a single request. This endpoint allows
        for efficient management of team memberships by processing multiple assignments at once. It is
        useful for organizations looking to streamline their team management processes.
      operationId: post-/settings/teams/2026-09/{teamId}/members/batch
      parameters:
      - name: teamId
        in: path
        description: The unique identifier of the team to which members will be assigned.
        required: true
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchInputTeamMemberAssignment'
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponseTeamMemberResponse'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - settings.users.teams.write
  /settings/teams/2026-09/{teamId}/members/{userId}:
    delete:
      tags:
      - Basic
      summary: Delete member
      description: Remove a specific member from a team in your HubSpot account. This operation requires
        specifying both the team and user identifiers. It is useful for managing team compositions by
        removing users who no longer need access or association with a particular team.
      operationId: delete-/settings/teams/2026-09/{teamId}/members/{userId}
      parameters:
      - name: teamId
        in: path
        description: The unique identifier of the team from which the member will be removed.
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: userId
        in: path
        description: The unique identifier of the user to be removed from the team.
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: type
        in: query
        description: Specifies the type of removal. Acceptable values are 'DEFAULT' or 'EXTRA'. Defaults
          to 'DEFAULT'.
        required: false
        style: form
        explode: true
        schema:
          type: string
          default: DEFAULT
          enum:
          - DEFAULT
          - EXTRA
      responses:
        '204':
          description: No content
          content: {}
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - settings.users.teams.write
components:
  schemas:
    BatchInputTeamMemberAssignment:
      required:
      - inputs
      type: object
      properties:
        inputs:
          type: array
          description: An array of team member assignments, where each item specifies the details of a
            team member to be assigned. Each item is of type 'TeamMemberAssignment'.
          items:
            $ref: '#/components/schemas/TeamMemberAssignment'
    BatchResponseTeamMemberResponse:
      required:
      - completedAt
      - results
      - startedAt
      - status
      type: object
      properties:
        completedAt:
          type: string
          description: The date and time when the batch operation was completed, in ISO 8601 format.
          format: date-time
        errors:
          type: array
          description: An array of StandardError objects detailing any errors that occurred during the
            batch operation.
          items:
            $ref: '#/components/schemas/StandardError'
        links:
          type: object
          additionalProperties:
            type: string
          description: A map of link names to associated URIs providing additional information about the
            batch operation.
        numErrors:
          type: integer
          description: The number of errors encountered during the batch operation.
          format: int32
        requestedAt:
          type: string
          description: The date and time when the batch operation was requested, in ISO 8601 format.
          format: date-time
        results:
          type: array
          description: An array of TeamMemberResponse objects representing the results of the batch operation.
          items:
            $ref: '#/components/schemas/TeamMemberResponse'
        startedAt:
          type: string
          description: The date and time when the batch operation started, in ISO 8601 format.
          format: date-time
        status:
          type: string
          description: The current status of the batch operation. Valid values include 'PENDING', 'PROCESSING',
            'CANCELED', and 'COMPLETE'.
          enum:
          - CANCELED
          - COMPLETE
          - PENDING
          - PROCESSING
    CollectionResponseTeamMemberResponseForwardPaging:
      required:
      - results
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/ForwardPaging'
        results:
          type: array
          description: An array of team member responses, each represented by a TeamMemberResponse object.
          items:
            $ref: '#/components/schemas/TeamMemberResponse'
    CollectionResponseTeamResponseForwardPaging:
      required:
      - results
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/ForwardPaging'
        results:
          type: array
          description: An array of team responses, each representing a team object.
          items:
            $ref: '#/components/schemas/TeamResponse'
    Error:
      required:
      - category
      - correlationId
      - message
      type: object
      properties:
        category:
          type: string
          description: The error category, represented as a string.
        context:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: An object containing context about the error condition. It includes additional
            properties where each is an array of strings.
          example: '{invalidPropertyName=[propertyValue], missingScopes=[scope1, scope2]}'
        correlationId:
          type: string
          description: A unique identifier for the request, formatted as a UUID. This should be included
            with any error reports or support tickets.
          format: uuid
          example: aeb5f871-7f07-4993-9211-075dc63e7cbf
        errors:
          type: array
          description: An array providing further information about the error, with each item being an
            ErrorDetail object.
          items:
            $ref: '#/components/schemas/ErrorDetail'
        links:
          type: object
          additionalProperties:
            type: string
          description: A map of link names to associated URIs, providing documentation about the error
            or recommended remediation steps. It is an object with string properties.
        message:
          type: string
          description: A human readable message describing the error along with remediation steps where
            appropriate. It is a string.
          example: An error occurred
        subCategory:
          type: string
          description: A specific category that contains more detailed information about the error. It
            is a string.
      description: Represents an error response returned by the API when an operation fails. This component
        is used in various endpoints to provide detailed information about the error encountered.
      example:
        message: Invalid input (details will vary based on the error)
        correlationId: aeb5f871-7f07-4993-9211-075dc63e7cbf
        category: VALIDATION_ERROR
        links:
          knowledge-base: https://www.hubspot.com/products/service/knowledge-base
    ErrorDetail:
      required:
      - message
      type: object
      properties:
        code:
          type: string
          description: The status code associated with the error detail.
        context:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Context about the error condition, represented as an object with additional properties
            that are arrays of strings.
          example: '{missingScopes=[scope1, scope2]}'
        in:
          type: string
          description: The name of the field or parameter in which the error was found.
        message:
          type: string
          description: A human readable message describing the error along with remediation steps where
            appropriate. This is a required field.
        subCategory:
          type: string
          description: A specific category that contains more specific detail about the error.
      description: Represents detailed information about an error that occurred in the API. This component
        is used to provide additional context and specifics about errors, typically as part of an error
        response.
    ForwardPaging:
      type: object
      properties:
        next:
          $ref: '#/components/schemas/NextPage'
      description: Paging information for forward-only pagination. Contains the next page reference when
        more results are available; omitted or empty on the last page.
    NextPage:
      required:
      - after
      type: object
      properties:
        after:
          type: string
          description: A string token representing the cursor position after the last successfully read
            resource. This is used to fetch the next set of results.
        link:
          type: string
          description: A string URL that provides the direct link to the next page of results.
      description: Specifies the paging information needed to retrieve the next set of results in a paginated
        API response
    StandardError:
      required:
      - category
      - context
      - errors
      - links
      - message
      - status
      type: object
      properties:
        category:
          type: string
          description: A string representing the category of the error.
        context:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: An object containing additional context about the error condition, with keys as
            context names and values as arrays of strings.
        errors:
          type: array
          description: An array of ErrorDetail objects providing further information about the error.
          items:
            $ref: '#/components/schemas/ErrorDetail'
        id:
          type: string
          description: A string that uniquely identifies the error instance.
        links:
          type: object
          additionalProperties:
            type: string
          description: An object mapping link names to associated URIs that contain documentation or recommended
            remediation steps for the error.
        message:
          type: string
          description: A string containing a human-readable message describing the error.
        status:
          type: string
          description: A string indicating the status of the error.
        subCategory:
          type: object
          properties: {}
          description: An object providing more specific details about the error category.
      description: Ye olde error
    TeamCreateRequest:
      required:
      - members
      - name
      type: object
      properties:
        members:
          type: array
          description: An array of team members to be assigned to the new team. Each member is represented
            by a TeamMemberAssignment object. This is a required field.
          items:
            $ref: '#/components/schemas/TeamMemberAssignment'
        name:
          type: string
          description: The name of the team to be created. This is a required field and must be a string.
        parentTeamId:
          type: string
          description: The unique identifier of the parent team, if the new team is a sub-team. This is
            an optional field and must be a string if provided.
    TeamMemberAssignment:
      required:
      - type
      - userId
      type: object
      properties:
        type:
          type: string
          description: The type of team member assignment. It is a string and can be either 'DEFAULT'
            or 'EXTRA'.
          enum:
          - DEFAULT
          - EXTRA
        userId:
          type: string
          description: The unique identifier for the user being assigned to the team. It is a string.
    TeamMemberResponse:
      required:
      - type
      - userId
      type: object
      properties:
        type:
          type: string
          description: The type of membership the user has in the team. Valid values are 'DEFAULT' and
            'EXTRA'.
          enum:
          - DEFAULT
          - EXTRA
        userId:
          type: string
          description: The unique identifier for the user, represented as a string.
    TeamResponse:
      required:
      - id
      - name
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the team, represented as a string.
        name:
          type: string
          description: The name of the team, represented as a string.
        parentTeamId:
          type: string
          description: The unique identifier of the parent team, if applicable, represented as a string.
    TeamUpdateRequest:
      required:
      - name
      - parentTeamId
      type: object
      properties:
        name:
          type: object
          properties: {}
          description: An object representing the new name for the team.
        parentTeamId:
          type: object
          properties: {}
          description: An object representing the ID of the parent team to which this team will be associated.
  responses:
    Error:
      description: An error occurred.
      content:
        '*/*':
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    developer_hapikey:
      type: apiKey
      name: hapikey
      in: query
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.hubspot.com/oauth/authorize
          tokenUrl: https://api.hubapi.com/oauth/v1/token
          scopes:
            settings.users.teams.read: ''
            settings.users.teams.write: ''
    private_apps:
      type: apiKey
      name: private-app
      in: header
    private_apps_legacy:
      type: apiKey
      name: private-app-legacy
      in: header
x-hubspot-product-tier-requirements:
  marketing: FREE
  sales: FREE
  service: FREE
  cms: FREE
  commerce: FREE
  crmHub: FREE
  dataHub: FREE