---
title: "Add user"
method: POST
path: "/users"
tags: ["users"]
---

# Add user

`POST /users`

Adds a user to the organization account.

> **Who can use this operation?**
>
> **Permissions:** System Admin

If successful, and user auto provisioning (UAP) is on, and user matches the auto provisioning rules, user is added to the org. If UAP is off, or user does not match UAP rules, user is invited to the org and must explicitly accept the invitation to join.

> **Note:** On user model plans, this operation sets `licensedSheetCreator` to `true`, regardless of the value provided in the request body.

> **Note:** In some specific scenarios, supplied attributes such as firstName and lastName may be ignored. For example, if you are inviting an existing Smartsheet user to join your organization account, and the invited user has not yet accepted your invitation, any supplied firstName and lastName are ignored.

## Query parameters

- `sendEmail` boolean

## Request body

- User — User object.
  - `id` number — User ID.
  - `admin` boolean — Indicates whether the user is a system admin (can manage user accounts and organization account).
  - `customWelcomeScreenViewed` string, date-time — Timestamp of viewing an Enterprise Custom Welcome Screen by the current user.
  - `email` string, email — User's primary email address.
  - `firstName` string — User's first name.
  - `groupAdmin` boolean — Indicates whether the user is a group admin (can create and edit groups).
  - `isInternal` boolean — Indicates whether the user is internal to the plan's domain. **Note:** It's present only when a `planId` query parameter is supplied.
  - `lastLogin` string, date-time — The timestamp of the user's last login to Smartsheet. This property is only included in the response when **all** of the following conditions are met: - The `include=lastLogin` query parameter is present - The user has logged in to Smartsheet at least once - The caller has System Admin permissions - The total number of users in the response is 100 or fewer This property is **excluded from the response** if **any** of the following conditions apply: - The `includeAll=true` query parameter is present - The `planId` query parameter is present - The `seatType` query parameter is present - The `pageSize` query parameter is set to a value greater than 100
  - `lastName` string — User's last name.
  - `licensedSheetCreator` boolean — Indicates whether the user is a licensed user (can create and own sheets). **Note:** On user model plans, the [`POST /users`](/api/smartsheet/openapi/users/add-user) operation sets `licensedSheetCreator` to `true`, regardless of the value provided in the request body.
  - `name` string — User's full name (read-only).
  - `profileImage` ProfileImage
    - `imageId` string — Unique image ID.
    - `height` integer — Image height.
    - `width` integer — Image width.
  - `provisionalExpirationDate` string, date-time, nullable — The expiration timestamp of the user's provisional seat type. It's null if the user doesn't have a `PROVISIONAL_MEMBER` seat type. **Note:** It's present only when a `planId` query parameter is supplied.
  - `resourceViewer` boolean — Indicates whether the user is a resource viewer (can access resource views).
  - `seatType` 'MEMBER' | 'PROVISIONAL_MEMBER' | 'CONTRIBUTOR' | 'GUEST' | 'VIEWER' — User's seat type. **Note:** It's only present when **either or both** the `planId` and `seatType` query parameters are supplied (available to system admins only). **DEPRECATED - As early as the sunset date specified in this [changelog entry](/api/smartsheet/changelog#deprecated-viewer-seat-type-in-favor-of-contributor-new), `VIEWER` will be removed and replaced by `CONTRIBUTOR` for all free-tier plans users.** Commenting and attachments are free to the `CONTRIBUTOR` seat type.
  - `seatTypeLastChangedAt` string, date-time — Timestamp of the user's last seat type change. **Note:** It's only present when **either or both** the `planId` and `seatType` query parameters are supplied (available to system admins only).
  - `sheetCount` number — **SUNSET** - The `sheetCount` attribute now holds the value `-1` and is included only if the retrieved user's `status` is `ACTIVE`.
  - `status` 'ACTIVE' | 'DECLINED' | 'PENDING' | 'DEACTIVATED' — User status, set to one of the listed enum values.

## Response `200`

Result object containing the newly created [User object](/api/smartsheet/openapi/users/user).

- object
  - `message` 'PARTIAL_SUCCESS' | 'SUCCESS' — Message that indicates the outcome of the request. (One of `SUCCESS` or `PARTIAL_SUCCESS`.)
  - `resultCode` 0 | 3 — * '0' Success * '3' Partial Success of Bulk Operation
  - `result` User — User object.
    - `id` number — User ID.
    - `admin` boolean — Indicates whether the user is a system admin (can manage user accounts and organization account).
    - `customWelcomeScreenViewed` string, date-time — Timestamp of viewing an Enterprise Custom Welcome Screen by the current user.
    - `email` string, email — User's primary email address.
    - `firstName` string — User's first name.
    - `groupAdmin` boolean — Indicates whether the user is a group admin (can create and edit groups).
    - `isInternal` boolean — Indicates whether the user is internal to the plan's domain. **Note:** It's present only when a `planId` query parameter is supplied.
    - `lastLogin` string, date-time — The timestamp of the user's last login to Smartsheet. This property is only included in the response when **all** of the following conditions are met: - The `include=lastLogin` query parameter is present - The user has logged in to Smartsheet at least once - The caller has System Admin permissions - The total number of users in the response is 100 or fewer This property is **excluded from the response** if **any** of the following conditions apply: - The `includeAll=true` query parameter is present - The `planId` query parameter is present - The `seatType` query parameter is present - The `pageSize` query parameter is set to a value greater than 100
    - `lastName` string — User's last name.
    - `licensedSheetCreator` boolean — Indicates whether the user is a licensed user (can create and own sheets). **Note:** On user model plans, the [`POST /users`](/api/smartsheet/openapi/users/add-user) operation sets `licensedSheetCreator` to `true`, regardless of the value provided in the request body.
    - `name` string — User's full name (read-only).
    - `profileImage` ProfileImage
      - `imageId` string — Unique image ID.
      - `height` integer — Image height.
      - `width` integer — Image width.
    - `provisionalExpirationDate` string, date-time, nullable — The expiration timestamp of the user's provisional seat type. It's null if the user doesn't have a `PROVISIONAL_MEMBER` seat type. **Note:** It's present only when a `planId` query parameter is supplied.
    - `resourceViewer` boolean — Indicates whether the user is a resource viewer (can access resource views).
    - `seatType` 'MEMBER' | 'PROVISIONAL_MEMBER' | 'CONTRIBUTOR' | 'GUEST' | 'VIEWER' — User's seat type. **Note:** It's only present when **either or both** the `planId` and `seatType` query parameters are supplied (available to system admins only). **DEPRECATED - As early as the sunset date specified in this [changelog entry](/api/smartsheet/changelog#deprecated-viewer-seat-type-in-favor-of-contributor-new), `VIEWER` will be removed and replaced by `CONTRIBUTOR` for all free-tier plans users.** Commenting and attachments are free to the `CONTRIBUTOR` seat type.
    - `seatTypeLastChangedAt` string, date-time — Timestamp of the user's last seat type change. **Note:** It's only present when **either or both** the `planId` and `seatType` query parameters are supplied (available to system admins only).
    - `sheetCount` number — **SUNSET** - The `sheetCount` attribute now holds the value `-1` and is included only if the retrieved user's `status` is `ACTIVE`.
    - `status` 'ACTIVE' | 'DECLINED' | 'PENDING' | 'DEACTIVATED' — User status, set to one of the listed enum values.

## Other responses

- `default` — If an error occurs because the request specified the alternate email address (that is, not the primary email address) of an existing Smartsheet user (to invite the user into the org), the Error object returned contains a detail attribute set to an array of objects, each object in the array having the following attributes: * alternateEmailAddress: User's alternate email address that was specified in the request * primaryEmailAddress: User's primary email address that must instead be specified for the operation For example: ```javascript { "errorCode": 5xxx, "message": "The specified email address (u1+1@smartsheet.com) is an alternate address for a user with the primary email address of u1@smartsheet.com. Please retry using their primary address." "detail": [ { "alternateEmailAddress": "u1+1@smartsheet.com", "primaryEmailAddress": "u1@smartsheet.com" } ] } ```

---

[API](https://skmtc.net/smartsheet/apis/smartsheet-openapi-reference.md) · [All operations](https://skmtc.net/smartsheet/apis/smartsheet-openapi-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/smartsheet/smartsheet-openapi-reference/versions/b4afda95fb51/schema)