Settings API | Teams (BETA)

Supported products

Scope requirements

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.

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

Parameter	Type	Description
`name`	String	The name of the team.
`members`	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:

{
  "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:

{
  "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}.

{
  "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:

{
  "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.

{
  "userId": "99001122",
  "type": "DEFAULT"
}

Parameter	Type	Description
`userId`	String	The ID of the user to add to the team.
`type`	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.

{
  "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.

​Create teams

​Retrieve teams

​Retrieve a single team

​Update teams

​Delete teams

​List team members

​Add team members

​Batch add team members

​Remove a team member