> ## 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: cb3d2be3-b69c-4c87-aafd-e24119dcaec7
---

# Settings API | User provisioning (BETA)

> Create and manage users in your HubSpot account programmatically.

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={[
  'crm.objects.users.read',
  'crm.objects.users.write',
  'settings.billing.write',
  'settings.users.read',
  'settings.users.write'
]}
    />
  </Accordion>
</AccordionGroup>

<BetaDisclaimerBanner />

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](/docs/api-reference/latest/crm/objects/users/guide) 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.

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

| Parameter                                | Type    | Description                                                                                                                         |
| ---------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `email` <RequiredIndicator />            | String  | The email address of the new user. Must be unique in the account.                                                                   |
| `sendWelcomeEmail` <RequiredIndicator /> | 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](#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](#seats) for how to retrieve available seat names.                         |

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.

<Warning>
  **Please note:** permission sets must be [created in HubSpot](https://knowledge.hubspot.com/user-management/create-permission-sets) before they can be assigned via the API.
</Warning>

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

```json theme={null}
{
  "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`.

<Warning>
  **Please note:** this endpoint requires the `settings.billing.write` scope.
</Warning>

```json theme={null}
{
  "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.                                          |