{ "openapi" : "3.0.1", "info" : { "title" : "Settings Teams", "description" : "Basepom for all HubSpot Projects", "version" : "2026-09-beta", "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-beta" : { "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-beta", "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", "example" : null } }, { "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", "example" : null } } ], "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CollectionResponseTeamResponseForwardPaging" }, "example" : null } } }, "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-beta", "parameters" : [ ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/TeamCreateRequest" }, "example" : null } }, "required" : true }, "responses" : { "201" : { "description" : "successful operation", "headers" : { "Location" : { "description" : "URL of the newly created resource", "style" : "simple", "explode" : false, "schema" : { "type" : "string", "example" : null } } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/TeamResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "settings.users.teams.write" ] } ] } }, "/settings/teams/2026-09-beta/{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-beta/{teamId}", "parameters" : [ { "name" : "teamId", "in" : "path", "description" : "The unique identifier of the team to retrieve.", "required" : true, "style" : "simple", "explode" : false, "schema" : { "type" : "string", "example" : null } } ], "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/TeamResponse" }, "example" : null } } }, "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-beta/{teamId}", "parameters" : [ { "name" : "teamId", "in" : "path", "description" : "The unique identifier of the team to delete.", "required" : true, "style" : "simple", "explode" : false, "schema" : { "type" : "string", "example" : null } } ], "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-beta/{teamId}", "parameters" : [ { "name" : "teamId", "in" : "path", "description" : "The unique identifier of the team to update.", "required" : true, "style" : "simple", "explode" : false, "schema" : { "type" : "string", "example" : null } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/TeamUpdateRequest" }, "example" : null } }, "required" : true }, "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/TeamResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "settings.users.teams.write" ] } ] } }, "/settings/teams/2026-09-beta/{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-beta/{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", "example" : null } }, { "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", "example" : null } }, { "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", "example" : null } } ], "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CollectionResponseTeamMemberResponseForwardPaging" }, "example" : null } } }, "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-beta/{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", "example" : null } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/TeamMemberAssignment" }, "example" : null } }, "required" : true }, "responses" : { "201" : { "description" : "successful operation", "headers" : { "Location" : { "description" : "URL of the newly created resource", "style" : "simple", "explode" : false, "schema" : { "type" : "string", "example" : null } } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/TeamMemberResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "settings.users.teams.write" ] } ] } }, "/settings/teams/2026-09-beta/{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-beta/{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", "example" : null } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BatchInputTeamMemberAssignment" }, "example" : null } }, "required" : true }, "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BatchResponseTeamMemberResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "settings.users.teams.write" ] } ] } }, "/settings/teams/2026-09-beta/{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-beta/{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", "example" : null } }, { "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", "example" : null } }, { "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", "example" : null, "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'.", "example" : null, "items" : { "$ref" : "#/components/schemas/TeamMemberAssignment" } } }, "example" : null }, "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", "example" : null }, "errors" : { "type" : "array", "description" : "An array of StandardError objects detailing any errors that occurred during the batch operation.", "example" : null, "items" : { "$ref" : "#/components/schemas/StandardError" } }, "links" : { "type" : "object", "additionalProperties" : { "type" : "string", "example" : null }, "description" : "A map of link names to associated URIs providing additional information about the batch operation.", "example" : null }, "numErrors" : { "type" : "integer", "description" : "The number of errors encountered during the batch operation.", "format" : "int32", "example" : null }, "requestedAt" : { "type" : "string", "description" : "The date and time when the batch operation was requested, in ISO 8601 format.", "format" : "date-time", "example" : null }, "results" : { "type" : "array", "description" : "An array of TeamMemberResponse objects representing the results of the batch operation.", "example" : null, "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", "example" : null }, "status" : { "type" : "string", "description" : "The current status of the batch operation. Valid values include 'PENDING', 'PROCESSING', 'CANCELED', and 'COMPLETE'.", "example" : null, "enum" : [ "CANCELED", "COMPLETE", "PENDING", "PROCESSING" ] } }, "example" : null }, "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.", "example" : null, "items" : { "$ref" : "#/components/schemas/TeamMemberResponse" } } }, "example" : null }, "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.", "example" : null, "items" : { "$ref" : "#/components/schemas/TeamResponse" } } }, "example" : null }, "Error" : { "required" : [ "category", "correlationId", "message" ], "type" : "object", "properties" : { "category" : { "type" : "string", "description" : "The error category, represented as a string.", "example" : null }, "context" : { "type" : "object", "additionalProperties" : { "type" : "array", "example" : null, "items" : { "type" : "string", "example" : null } }, "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.", "example" : null, "items" : { "$ref" : "#/components/schemas/ErrorDetail" } }, "links" : { "type" : "object", "additionalProperties" : { "type" : "string", "example" : null }, "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.", "example" : null }, "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.", "example" : null } }, "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.", "example" : null }, "context" : { "type" : "object", "additionalProperties" : { "type" : "array", "example" : null, "items" : { "type" : "string", "example" : null } }, "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.", "example" : null }, "message" : { "type" : "string", "description" : "A human readable message describing the error along with remediation steps where appropriate. This is a required field.", "example" : null }, "subCategory" : { "type" : "string", "description" : "A specific category that contains more specific detail about the error.", "example" : null } }, "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.", "example" : null }, "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.", "example" : null }, "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.", "example" : null }, "link" : { "type" : "string", "description" : "A string URL that provides the direct link to the next page of results.", "example" : null } }, "description" : "Specifies the paging information needed to retrieve the next set of results in a paginated API response", "example" : null }, "StandardError" : { "required" : [ "category", "context", "errors", "links", "message", "status" ], "type" : "object", "properties" : { "category" : { "type" : "string", "description" : "A string representing the category of the error.", "example" : null }, "context" : { "type" : "object", "additionalProperties" : { "type" : "array", "example" : null, "items" : { "type" : "string", "example" : null } }, "description" : "An object containing additional context about the error condition, with keys as context names and values as arrays of strings.", "example" : null }, "errors" : { "type" : "array", "description" : "An array of ErrorDetail objects providing further information about the error.", "example" : null, "items" : { "$ref" : "#/components/schemas/ErrorDetail" } }, "id" : { "type" : "string", "description" : "A string that uniquely identifies the error instance.", "example" : null }, "links" : { "type" : "object", "additionalProperties" : { "type" : "string", "example" : null }, "description" : "An object mapping link names to associated URIs that contain documentation or recommended remediation steps for the error.", "example" : null }, "message" : { "type" : "string", "description" : "A string containing a human-readable message describing the error.", "example" : null }, "status" : { "type" : "string", "description" : "A string indicating the status of the error.", "example" : null }, "subCategory" : { "type" : "object", "properties" : { }, "description" : "An object providing more specific details about the error category.", "example" : null } }, "description" : "Ye olde error", "example" : null }, "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.", "example" : null, "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.", "example" : null }, "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.", "example" : null } }, "example" : null }, "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'.", "example" : null, "enum" : [ "DEFAULT", "EXTRA" ] }, "userId" : { "type" : "string", "description" : "The unique identifier for the user being assigned to the team. It is a string.", "example" : null } }, "example" : null }, "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'.", "example" : null, "enum" : [ "DEFAULT", "EXTRA" ] }, "userId" : { "type" : "string", "description" : "The unique identifier for the user, represented as a string.", "example" : null } }, "example" : null }, "TeamResponse" : { "required" : [ "id", "name" ], "type" : "object", "properties" : { "id" : { "type" : "string", "description" : "The unique identifier for the team, represented as a string.", "example" : null }, "name" : { "type" : "string", "description" : "The name of the team, represented as a string.", "example" : null }, "parentTeamId" : { "type" : "string", "description" : "The unique identifier of the parent team, if applicable, represented as a string.", "example" : null } }, "example" : null }, "TeamUpdateRequest" : { "required" : [ "name", "parentTeamId" ], "type" : "object", "properties" : { "name" : { "type" : "object", "properties" : { }, "description" : "An object representing the new name for the team.", "example" : null }, "parentTeamId" : { "type" : "object", "properties" : { }, "description" : "An object representing the ID of the parent team to which this team will be associated.", "example" : null } }, "example" : null } }, "responses" : { "Error" : { "description" : "An error occurred.", "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/Error" }, "example" : null } } } }, "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" } }