Smartsheet logo

Methods

List Users

Gets a list of users in the organization account. To filter by email, use the optional email query string parameter to specify a list of users' email addresses.

NOTE: If the API request is submitted by a system administrator, the following User object attributes are included in the response (else, they are omitted from the response):

  • admin
  • groupAdmin
  • licensedSheetCreator
  • resourceViewer
  • sheetCount (omitted if the status attribute is not ACTIVE)
  • status

NOTE: If the API request is submitted by a system administrator of an Enterprise account, and Custom Welcome Screen is enabled, the following User object attributes are included in the response (else, they are omitted from the response):

Authorizations:
APITokenOAuth2 (READ_USERS)
query Parameters
email
string

Comma-separated list of email addresses on which to filter the results.

include
string

If the API request is submitted by a system administrator and when specified with a value of 'lastLogin', response includes a lastLogin attribute for each user that indicates the Last login date/time of the user.

Note If the number of users included in the response is > 100, you must paginate your query to see the lastLogin attribute. For large responses, the lastLogin attribute is never included.

includeAll
boolean
Default: false

If true, include all results, that is, do not paginate. Mutually exclusive with page and pageSize (they are ignored if includeAll=true is specified).

string or number

When specified with a date and time value, response only includes the objects that are modified on or after the date and time specified. If you need to keep track of frequent changes, it may be more useful to use Get Sheet Version.

numericDates
boolean
Default: false

You can optionally choose to receive and send dates/times in numeric format, as milliseconds since the UNIX epoch (midnight on January 1, 1970 in UTC time), using the query string parameter numericDates with a value of true. This query parameter works for any API request.

page
number
Default: 1

Which page to return. Defaults to 1 if not specified. If you specify a value greater than the total number of pages, you'll receive an empty data set.

pageSize
number
Default: 100

The maximum number of items to return per page. Unless otherwise stated for a specific endpoint, defaults to 100. If only page is specified, defaults to a page size of 100. For reports, the default is 100 rows. If you need larger sets of data from your report, returns a maximum of 10,000 rows per request.

header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789

Responses

Request samples 

curl 'https://api.smartsheet.com/2.0/users?email=john.doe@smartsheet.com&include=lastLogin' \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789"

Response samples

Content type
application/json
{
  • "pageNumber": 1,
  • "pageSize": 50,
  • "totalPages": 25,
  • "totalCount": 136,
  • "data": [
    ]
}

Add User

Adds a user to the organization account.

  • This operation is only available to system administrators

  • 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.

  • 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.

Authorizations:
APITokenOAuth2 (ADMIN_USERS)
query Parameters
sendEmail
boolean
Default: false

Either true or false to indicate whether to notify the user by email. Default is false. If true, limit is 1000 emails.

header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
Request Body schema: application/json

The User to be created

admin
boolean
Default: false

Indicates whether the user is a system admin (can manage user accounts and organization account).

email
string <email>

User's primary email address.

firstName
string

User's first name.

groupAdmin
boolean
Default: false

Indicates whether the user is a group admin (can create and edit groups).

lastName
string

User's last name.

licensedSheetCreator
boolean
Default: false

Indicates whether the user is a licensed user (can create and own sheets).

object
resourceViewer
boolean
Default: false

Indicates whether the user is a resource viewer (can access resource views).

status
string

User status, set to one of the listed enum values.

Enum: "ACTIVE" "DECLINED" "PENDING" "DEACTIVATED"

Responses

Request samples

Content type
application/json
{
  • "admin": true,
  • "email": "jane.doe@smartsheet.com",
  • "firstName": "Jane",
  • "groupAdmin": true,
  • "lastName": "Doe",
  • "licensedSheetCreator": true,
  • "profileImage": {
    },
  • "resourceViewer": true,
  • "status": "ACTIVE"
}

Response samples

Content type
application/json
{
  • "message": "SUCCESS",
  • "resultCode": 0,
  • "result": {
    }
}

Get Current User

Gets the current user

NOTE: For system administrators, the following UserProfile attributes are included in the response:

  • customWelcomeScreenViewed (only returned when an Enterprise user has viewed the Custom Welcome Screen)
  • lastLogin (only returned if the user has logged in)
  • sheetCount (only returned if the status attribute is ACTIVE)
Authorizations:
APITokenOAuth2
query Parameters
include
string

When specified with a value of 'groups', response includes an array of groups (groupId, name, and description only) that the user is a member of.

Value: "groups"
header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789

Responses

Request samples 

curl https://api.smartsheet.com/2.0/users/me \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789"

Response samples

Content type
application/json
{
  • "id": 48569348493401200,
  • "account": {
    },
  • "admin": true,
  • "alternateEmails": {
    },
  • "company": "Smartsheet",
  • "customWelcomeScreenViewed": "2020-08-25T12:15:47Z",
  • "department": "Engineering",
  • "email": "john.doe@smartsheet.com",
  • "firstName": "John",
  • "groupAdmin": true,
  • "jiraAdmin": true,
  • "lastLogin": "2020-10-31T12:15:47Z",
  • "lastName": "Doe",
  • "licensedSheetCreator": true,
  • "locale": "en_US",
  • "mobilePhone": "555-867-5309",
  • "profileImage": {
    },
  • "resourceViewer": true,
  • "role": "Software Developer",
  • "salesforceAdmin": false,
  • "salesforceUser": false,
  • "sheetCount": 42,
  • "timeZone": "US/Pacific",
  • "title": "Senior Software Engineer",
  • "workPhone": "844-324-2360",
  • "data": [
    ]
}

Get User

Gets the user specified in the URL.

  • NOTE: For system administrators, the following UserProfile attributes are included in the response):
    • admin
    • customWelcomeScreenViewed (only returned when an Enterprise user has viewed the Custom Welcome Screen)
    • groupAdmin
    • lastLogin (only returned if the user has logged in)
    • licensedSheetCreator
    • resourceViewer
    • sheetCount (only returned if the status attribute is ACTIVE)
    • status
Authorizations:
APITokenOAuth2 (READ_USERS)
path Parameters
userId
required
number

User Id

header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789

Responses

Request samples 

curl https://api.smartsheet.com/2.0/users/{userId} \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789"

Response samples

Content type
application/json
{
  • "id": 48569348493401200,
  • "account": {
    },
  • "admin": true,
  • "alternateEmails": {
    },
  • "company": "Smartsheet",
  • "customWelcomeScreenViewed": "2020-08-25T12:15:47Z",
  • "department": "Engineering",
  • "email": "john.doe@smartsheet.com",
  • "firstName": "John",
  • "groupAdmin": true,
  • "jiraAdmin": true,
  • "lastLogin": "2020-10-31T12:15:47Z",
  • "lastName": "Doe",
  • "licensedSheetCreator": true,
  • "locale": "en_US",
  • "mobilePhone": "555-867-5309",
  • "profileImage": {
    },
  • "resourceViewer": true,
  • "role": "Software Developer",
  • "salesforceAdmin": false,
  • "salesforceUser": false,
  • "sheetCount": 42,
  • "timeZone": "US/Pacific",
  • "title": "Senior Software Engineer",
  • "workPhone": "844-324-2360"
}

Remove User

Removes a user from an organization account. User is transitioned to a free collaborator with read-only access to owned reports, sheets, Sights, workspaces, and any shared templates (unless those are optionally transferred to another user).

  • This operation is only available to system administrators

  • If the transferTo parameter is specified and the removed user owns groups, the user specified via the transferTo parameter must have group admin rights.

  • The transferTo and transferSheets parameters cannot be specified for a user who has not yet accepted an invitation to join the organization account (that is, if user status=PENDING).

Authorizations:
APITokenOAuth2 (ADMIN_USERS)
path Parameters
userId
required
number

User Id

header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
Request Body schema: application/json
removeFromSharing
boolean
  • Set to true to remove the user from sharing for all sheets/workspaces in the organization account. If not specified, user is not removed from sharing.
transferSheets
boolean
Default: false
  • If true, and transferTo is specified, the removed user's sheets are transferred. Else, sheets are not transferred.
transferTo
number

(Required if user owns groups.)

  • The Id of the user to transfer ownership to.
  • If the user being removed owns groups, they are transferred to this user. If the user owns sheets, and transferSheets is true, the removed user's sheets are transferred to this user.

Responses

Request samples

Content type
application/json
{
  • "removeFromSharing": true,
  • "transferSheets": true,
  • "transferTo": 94094820842
}

Response samples

Content type
application/json
{
  • "message": "SUCCESS",
  • "resultCode": 0
}

Update User

Updates the user specified in the URL.

Authorizations:
APITokenOAuth2 (ADMIN_USERS)
path Parameters
userId
required
number

User Id

header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
Request Body schema: application/json

User object containing at least one of the following attributes:

  • admin (required)
  • licensedSheetCreator (required)
  • firstName (optional)
  • groupAdmin (optional)
  • lastName (optional)
  • resourceViewer (optional)
admin
boolean
Default: false

Indicates whether the user is a system admin (can manage user accounts and organization account).

licensedSheetCreator
boolean
Default: false

Indicates whether the user is a licensed user (can create and own sheets).

firstName
string

User's first name.

lastName
string

User's last name.

groupAdmin
boolean
Default: false

Indicates whether the user is a group admin (can create and edit groups).

resourceViewer
boolean
Default: false

Indicates whether the user is a resource viewer (can access resource views).

Responses

Request samples

Content type
application/json
{
  • "admin": true,
  • "licensedSheetCreator": true,
  • "firstName": "Jane",
  • "lastName": "Doe",
  • "groupAdmin": true,
  • "resourceViewer": true
}

Response samples

Content type
application/json
{
  • "message": "SUCCESS",
  • "resultCode": 0,
  • "data": [
    ]
}

Deactivate User

Deactivates a user in an organization account. User will no longer be able to access Smartsheet in any way. User's assets will continue to be owned by this user until they are transferred to another user.

This operation is only available to system administrators of Enterprise organizations. Additionally, if organizations have Enterprise Plan Manager (EPM) enabled, a system administrator of the main plan can provide a userId for a user belonging to a managed plan within the EPM hierarchy.

NOTES:

  • Currently unavailable for Smartsheet GOV (aka the Gov environment).
  • This operation does not apply to users with an ISP based domain account (outlook.com, gmail.com, hotmail.com, live.com, yahoo.com, aol.com, verizon.net, rocketmail.com, comcast.net, icloud.com, charter.net, web.de, mail.com, email.com, usa.com, duck.com, mail.ru).
Authorizations:
APITokenOAuth2 (ADMIN_USERS)
path Parameters
userId
required
number

User Id

header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789

Responses

Request samples 

curl https://api.smartsheet.com/2.0/users/{userId}/deactivate \
 -H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789" \
 -H "Content-Type: application/json" \
-X POST

Response samples

Content type
application/json
{
  • "message": "SUCCESS",
  • "resultCode": 0
}

Update User Profile Image

Uploads an image to the user profile.

Uploading a profile image differs from Adding an Image to a Cell in the following ways:

  • A Content-Length header is not required
  • Allowable file types are limited to: gif, jpg, and png
  • Maximum file size is determined by the following rules:
    • If you have not defined a custom size and the image is larger than 1050 x 1050 pixels, Smartsheet scales the image down to 1050 x 1050
    • If you have defined a custom size, Smartsheet uses that as the file size max
  • If the image is not square, Smartsheet uses a solid color to pad the image
Authorizations:
APITokenOAuth2 (WRITE_SHEETS)
path Parameters
userId
required
number

User Id

header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
Content-Type
string
Default: application/json

Required for POST and PUT requests. Defines the structure for the request body.

Request Body schema:
application/octet-stream
application/octet-stream
multipart/form-data
application/json
string <binary>

Responses

Request samples

Content type
application/octet-stream
application/octet-stream
multipart/form-data
application/json
No sample

Response samples

Content type
application/json
{
  • "message": "SUCCESS",
  • "resultCode": 0,
  • "data": [
    ]
}

Reactivate User

Reactivates a user in an organization account. User will regain to access Smartsheet and will have the same roles as when they were deactivated.

This operation is only available to system administrators of Enterprise organizations. Additionally, if organizations have Enterprise Plan Manager (EPM) enabled, a system administrator of the main plan can provide a userId for a user belonging to a managed plan within the EPM hierarchy.

NOTES:

  • Currently unavailable for Smartsheet GOV (aka the Gov environment).
  • This operation does not apply to users with an ISP based domain account (outlook.com, gmail.com, hotmail.com, live.com, yahoo.com, aol.com, verizon.net, rocketmail.com, comcast.net, icloud.com, charter.net, web.de, mail.com, email.com, usa.com, duck.com, mail.ru).
Authorizations:
APITokenOAuth2 (ADMIN_USERS)
path Parameters
userId
required
number

User Id

header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789

Responses

Request samples 

curl https://api.smartsheet.com/2.0/users/{userId}/reactivate \
 -H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789" \
 -H "Content-Type: application/json" \
-X POST

Response samples

Content type
application/json
{
  • "message": "SUCCESS",
  • "resultCode": 0
}
➔ Next to Webhooks Basics