Settings API | User provisioning (BETA)

Supported products

Scope requirements

Use the user provisioning API to create and manage users in your HubSpot account, including assigning roles, teams, and seats. You can also set user firstName and lastName properties through this API. To retrieve and update other user information, such as job title and working hours, use the users API instead.

Create users

To create a user, make a POST request to /settings/users/2026-09-beta. In the request body, include the user’s email address and the sendWelcomeEmail flag. You can optionally include a role, team assignments, seat names, and basic profile information.

{
  "email": "jdoe@example.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "roleId": "1234",
  "primaryTeamId": "5678",
  "secondaryTeamIds": ["9012"],
  "seatNames": ["sales-seat"],
  "sendWelcomeEmail": true
}

Parameter	Type	Description
`email`	String	The email address of the new user. Must be unique in the account.
`sendWelcomeEmail`	Boolean	Whether to send a welcome email to the new user upon creation.
`firstName`	String	The user’s first name.
`lastName`	String	The user’s last name.
`roleId`	String	The ID of the permission set to assign to the user. See permission sets for how to retrieve available role IDs.
`primaryTeamId`	String	The ID of the user’s primary team.
`secondaryTeamIds`	Array	An array of team IDs to add the user to as a secondary member.
`seatNames`	Array	An array of seat names to assign to the user. See seats for how to retrieve available seat names.

A successful request returns a 201 response with the created user:

{
  "id": "11223344",
  "email": "jdoe@example.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "roleId": "1234",
  "roleIds": ["1234"],
  "primaryTeamId": "5678",
  "secondaryTeamIds": ["9012"],
  "seatNames": ["sales-seat"],
  "superAdmin": false
}

Retrieve users

To retrieve all users in your account, make a GET request to /settings/users/2026-09-beta. You can use the following query parameters to paginate through the 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 user

To retrieve a specific user, make a GET request to /settings/users/2026-09-beta/{userId}. By default, userId refers to the user’s numeric ID. To retrieve a user by email address instead, include the idProperty=EMAIL query parameter. For example: /settings/users/2026-09-beta/jdoe@example.com?idProperty=EMAIL You can use the idProperty parameter in any endpoint that accepts userId as a path parameter. A successful request returns the user object:

{
  "id": "11223344",
  "email": "jdoe@example.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "roleIds": ["1234"],
  "primaryTeamId": "5678",
  "secondaryTeamIds": [],
  "seatNames": ["sales-seat"],
  "superAdmin": false
}

Update users

To update a user’s details, make a PUT request to /settings/users/2026-09-beta/{userId}. In the request body, include only the fields you want to update:

{
  "firstName": "Jane",
  "lastName": "Smith",
  "roleId": "5678",
  "primaryTeamId": "9012",
  "secondaryTeamIds": ["3456"],
  "seatNames": ["sales-seat", "service-seat"]
}

Parameter	Type	Description
`firstName`	String	The user’s updated first name.
`lastName`	String	The user’s updated last name.
`roleId`	String	The ID of the permission set to assign to the user, replacing any existing role.
`primaryTeamId`	String	The ID of the user’s primary team.
`secondaryTeamIds`	Array	An array of team IDs for the user’s secondary team memberships, replacing any existing secondary teams.
`seatNames`	Array	An array of seat names to assign to the user, replacing any existing seat assignments.

As with retrieval, you can target a user by email by appending ?idProperty=EMAIL to the request URL.

Delete users

To remove a user from your account, make a DELETE request to /settings/users/2026-09-beta/{userId}. A successful request returns a 204 No Content response. To specify a user by email instead of ID, include ?idProperty=EMAIL: /settings/users/2026-09-beta/jdoe@example.com?idProperty=EMAIL

Permission sets

HubSpot accounts can define permission sets to manage user access at scale. Once you create a permission set in HubSpot and configure its permissions, you can assign users to it by providing the permission set’s ID as the roleId when creating or updating a user.

Please note: permission sets must be created in HubSpot before they can be assigned via the API.

To retrieve all available permission sets in your account, make a GET request to /settings/users/2026-09-beta/roles:

{
  "results": [
    {
      "id": "1234",
      "name": "Sales representative",
      "requiresBillingWrite": false
    }
  ]
}

Field	Type	Description
`id`	String	The unique ID of the permission set. Use this as the `roleId` when creating or updating users.
`name`	String	The name of the permission set as it appears in HubSpot.
`requiresBillingWrite`	Boolean	Whether the `settings.billing.write` scope is required to modify this permission set.

Seats

Seats control user access to specific HubSpot products. To retrieve all available seats and remaining availability, make a GET request to /settings/users/2026-09-beta/seats.

Please note: this endpoint requires the settings.billing.write scope.

{
  "results": [
    {
      "name": "sales-seat",
      "description": "Access to HubSpot Sales Hub tools.",
      "remainingSeats": 5
    }
  ]
}

Field	Type	Description
`name`	String	The seat name. Use this value in the `seatNames` field when creating or updating users.
`description`	String	A description of what the seat grants access to.
`remainingSeats`	Integer	The number of seats still available to assign.

​Create users

​Retrieve users

​Retrieve a single user

​Update users

​Delete users

​Permission sets

​Seats

Create users

Retrieve users

Retrieve a single user

Update users

Delete users

Permission sets

Seats