> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

---
id: 9d7c319c-6942-4173-abe5-f24ded75cd5d
---

# Settings API | Teams (BETA)

> Create and manage teams in your HubSpot account.

export const BetaDisclaimerBanner = () => <Warning>
        This functionality is currently in beta. By participating in this beta, you agree to HubSpot's <a href="https://legal.hubspot.com/developer-terms">Developer Terms</a> and <a href="https://legal.hubspot.com/developerbetaterms">Developer Beta Terms</a>. Note that the functionality is still under active development and is subject to change based on testing and feedback.
    </Warning>;

export const SupportedProducts = ({marketing, sales, service, cms, data, commerce, crm, marketingLevel, salesLevel, serviceLevel, cmsLevel, dataLevel, commerceLevel, crmLevel}) => {
  const translations = {
    description: "Requires one of the following products or higher.",
    productNames: {
      marketing: "Marketing Hub",
      sales: "Sales Hub",
      service: "Service Hub",
      cms: "Content Hub",
      data: "Data Hub",
      commerce: "Revenue Hub",
      crm: "Smart CRM"
    },
    tiers: {
      free: "Free",
      starter: "Starter",
      professional: "Professional",
      enterprise: "Enterprise"
    }
  };
  const translateTier = tier => {
    if (!tier) return '';
    const lowerTier = tier.toLowerCase();
    return translations.tiers[lowerTier] || tier;
  };
  const products = [{
    name: marketing ? translations.productNames.marketing : '',
    level: translateTier(marketingLevel),
    icon: "https://mintlify-assets.b-cdn.net/Icons/marketing-bolt.svg",
    alt: "Marketing Hub"
  }, {
    name: sales ? translations.productNames.sales : '',
    level: translateTier(salesLevel),
    icon: "https://mintlify-assets.b-cdn.net/Icons/sales-star.svg",
    alt: "Sales Hub"
  }, {
    name: service ? translations.productNames.service : '',
    level: translateTier(serviceLevel),
    icon: "https://mintlify-assets.b-cdn.net/Icons/service-heart.svg",
    alt: "Service Hub"
  }, {
    name: cms ? translations.productNames.cms : '',
    level: translateTier(cmsLevel),
    icon: "https://mintlify-assets.b-cdn.net/Icons/content-play.svg",
    alt: "Content Hub"
  }, {
    name: data ? translations.productNames.data : '',
    level: translateTier(dataLevel),
    icon: "https://developers.hubspot.com/hubfs/Knowledge_Base_2023-24-25/subscription_key_icons/operations_icon.svg",
    alt: "Data Hub"
  }, {
    name: commerce ? translations.productNames.commerce : '',
    level: translateTier(commerceLevel),
    icon: "https://developers.hubspot.com/hubfs/Knowledge_Base/subscription_key_icons/commerce_icon.svg",
    alt: "Revenue Hub"
  }, {
    name: crm ? translations.productNames.crm : '',
    level: translateTier(crmLevel),
    icon: "https://developer.hubspot.com/hubfs/Knowledge_Base_2023-24-25/developer/icons/SmartCRM.svg",
    alt: "Smart CRM"
  }].filter(product => product.name && product.level);
  if (products.length === 0) return null;
  return <div>
      <div className="text-sm mb-2">{translations.description}</div>
      <div className={`grid ${products.length === 1 ? 'grid-cols-1' : 'grid-cols-2'} gap-1.5`}>
        {products.map((product, index) => <div key={index} style={{
    display: 'flex',
    alignItems: 'center'
  }}>
            <img src={product.icon} alt={product.alt} className="w-3.5 h-3.5 mr-1.5 mt-2.5 mb-2.5 flex-shrink-0 align-middle" />
            <span className="font-medium mr-1 text-sm">{product.name} -</span>
            <span className="text-sm">{product.level}</span>
          </div>)}
      </div>
    </div>;
};

export const RequiredIndicator = () => {
  return <span className="required-indicator">
      required
    </span>;
};

export const ScopesList = ({scopes = [], description = "This API requires one of the following scopes:"}) => {
  if (!scopes || scopes.length === 0) {
    return null;
  }
  const sortedScopes = scopes.sort((a, b) => a.localeCompare(b));
  return <div>
      <div className="text-sm mb-2">{description}</div>
      <div>
        {sortedScopes.map((scope, index) => <div key={index}>
            <code>
              <span className="text-xs">{scope}</span>
            </code>
          </div>)}
      </div>
    </div>;
};

<AccordionGroup>
  <Accordion title="Supported products" defaultOpen="true" icon="cubes">
    <SupportedProducts marketing={true} sales={true} service={true} cms={true} marketingLevel="FREE" salesLevel="FREE" serviceLevel="FREE" cmsLevel="FREE" />
  </Accordion>

  <Accordion title="Scope requirements">
    <ScopesList
      scopes={[
  'settings.users.teams.read',
  'settings.users.teams.write'
]}
    />
  </Accordion>
</AccordionGroup>

<BetaDisclaimerBanner />

Use the teams API to create and manage teams in your HubSpot account. Teams help you organize users and control access to records and tools across your organization. You can create hierarchical team structures using parent and child teams, and assign users as primary or secondary team members.

## Create teams

To create a team, make a `POST` request to `/settings/teams/2026-09-beta`.

In the request body, include the team's `name` and initial `members`. You can optionally assign the team a parent team to create a hierarchical structure.

```json theme={null}
{
  "name": "West Coast Sales",
  "parentTeamId": "1001",
  "members": [
    {
      "userId": "11223344",
      "type": "DEFAULT"
    },
    {
      "userId": "55667788",
      "type": "EXTRA"
    }
  ]
}
```

| Parameter                       | Type   | Description                                                                                          |
| ------------------------------- | ------ | ---------------------------------------------------------------------------------------------------- |
| `name` <RequiredIndicator />    | String | The name of the team.                                                                                |
| `members` <RequiredIndicator /> | Array  | An array of users to add to the team at creation. Each entry must include a `userId` and `type`.     |
| `members[].userId`              | String | The ID of the user to add to the team.                                                               |
| `members[].type`                | String | The member's role on the team. Use `DEFAULT` for a primary member or `EXTRA` for a secondary member. |
| `parentTeamId`                  | String | The ID of a parent team. Providing this makes the new team a sub-team of the specified parent.       |

A successful request returns a `201` response with the created team:

```json theme={null}
{
  "id": "2001",
  "name": "West Coast Sales",
  "parentTeamId": "1001"
}
```

## Retrieve teams

To retrieve all teams in your account, make a `GET` request to `/settings/teams/2026-09-beta`.

Use the `limit` and `after` query parameters to paginate through results:

| Parameter | Description                                                                                               |
| --------- | --------------------------------------------------------------------------------------------------------- |
| `limit`   | The maximum number of results to return per page.                                                         |
| `after`   | A cursor token from the `paging.next.after` field of a previous response, used to retrieve the next page. |

### Retrieve a single team

To retrieve a specific team by ID, make a `GET` request to `/settings/teams/2026-09-beta/{teamId}`.

A successful request returns the team object:

```json theme={null}
{
  "id": "2001",
  "name": "West Coast Sales",
  "parentTeamId": "1001"
}
```

## Update teams

To update a team's name or parent team, make a `PATCH` request to `/settings/teams/2026-09-beta/{teamId}`.

```json theme={null}
{
  "name": "West Coast Enterprise Sales",
  "parentTeamId": "1002"
}
```

| Parameter      | Type   | Description                                                                     |
| -------------- | ------ | ------------------------------------------------------------------------------- |
| `name`         | String | The updated name for the team.                                                  |
| `parentTeamId` | String | The ID of the parent team to assign. Set to `null` to remove the team's parent. |

A successful request returns the updated team object.

## Delete teams

To delete a team, make a `DELETE` request to `/settings/teams/2026-09-beta/{teamId}`.

A successful request returns a `204 No Content` response.

## List team members

To retrieve the members of a specific team, make a `GET` request to `/settings/teams/2026-09-beta/{teamId}/members`.

Use the `limit` and `after` query parameters to paginate through results.

A successful request returns a paginated list of team members:

```json theme={null}
{
  "results": [
    {
      "userId": "11223344",
      "type": "DEFAULT"
    },
    {
      "userId": "55667788",
      "type": "EXTRA"
    }
  ],
  "paging": {
    "next": {
      "after": "NTU2Nzc4OA=="
    }
  }
}
```

Each result includes:

| Field    | Type   | Description                                                                           |
| -------- | ------ | ------------------------------------------------------------------------------------- |
| `userId` | String | The ID of the user.                                                                   |
| `type`   | String | The user's membership type: `DEFAULT` (primary member) or `EXTRA` (secondary member). |

## Add team members

To add a member to a team, make a `POST` request to `/settings/teams/2026-09-beta/{teamId}/members`.

```json theme={null}
{
  "userId": "99001122",
  "type": "DEFAULT"
}
```

| Parameter                      | Type   | Description                                                                             |
| ------------------------------ | ------ | --------------------------------------------------------------------------------------- |
| `userId` <RequiredIndicator /> | String | The ID of the user to add to the team.                                                  |
| `type` <RequiredIndicator />   | String | The membership type: `DEFAULT` for a primary member, or `EXTRA` for a secondary member. |

A successful request returns a `201` response with the new team member entry.

### Batch add team members

To add multiple users to a team in a single request, make a `POST` request to `/settings/teams/2026-09-beta/{teamId}/members/batch`.

```json theme={null}
{
  "inputs": [
    {
      "userId": "99001122",
      "type": "DEFAULT"
    },
    {
      "userId": "33445566",
      "type": "EXTRA"
    }
  ]
}
```

A successful request returns a `200` response with the results of each assignment.

## Remove a team member

To remove a user from a team, make a `DELETE` request to `/settings/teams/2026-09-beta/{teamId}/members/{userId}`.

By default, this removes the user's primary (`DEFAULT`) membership. To remove a secondary (`EXTRA`) membership instead, include the `type=EXTRA` query parameter:

`/settings/teams/2026-09-beta/{teamId}/members/{userId}?type=EXTRA`

A successful request returns a `204 No Content` response.