Smartsheet API 2.0

Overview

Introduction

Base URL: https://api.smartsheet.com/2.0

The Smartsheet API provides programmatic access to Smartsheet features and data. In designing the API, our goal was to make it simple, intuitive, and predictable. We do our best to adhere to common open and widely accepted standards, including REST for access, JSON format for the data, and OAuth for Authentication and Authorization. This API assumes a good working knowledge of the Smartsheet application UI, concepts and terminology.

RESTful Architecture

Resources:

/favorites
/folders
/groups
/home
/reports
/search
/serverinfo
/sheets
/sheets/{id}/rows
/sheets/{id}/columns
/sheets/{id}/attachments
/sheets/{id}/discussions
/templates
/token
/users
/workspaces

Everything in Smartsheet is represented as an object with a defined structure. For example, the “Home” object contains a list of your Sheets, Folders, Reports, Templates, and Workspaces, and a Sheet object contains Columns, Rows, Attachments, and Discussions. All aspects of Smartsheet are modeled as structured objects.

URL structure follows typical resource-oriented conventions. For example, to get a list of sheets, use GET https://api.smartsheet.com/2.0/sheets. This will return a list of Sheet objects, where each Sheet will have an “id” attribute. To get details on a particular sheet, use GET https://api.smartsheet.com/2.0/sheets/123456, where 123456 is the “id” of the Sheet you want. Similarly, to share a sheet, POST a Share object to https://api.smartsheet.com/2.0/sheets/123456/shares.

HTTP Standards

All actions taken through the API are done via HTTP using standard HTTP methods: GET (to retrieve an object), POST (to create), PUT (to modify), and DELETE. Standard HTTP Response codes are used to indicate success and error conditions.

Input / Output Format

Unless otherwise specified, all API endpoints expect request body data to be in JSON, and the response body data is returned as JSON. The following HTTP request headers may be required, depending on the operation and endpoint being invoked:

Content-Type For POST and PUT requests, must be set to the appropriate value (typically application/json). Ignored for GET and DELETE requests.
Accept Optional; if not specified, */* is assumed (i.e. any response type is accepted), else it must match the output of the invoked endpoint (typically application/json).

Example Requests & Responses

With every API operation we provide a sample request and a sample response. The sample requests shown on the cURL tab use the command line data transfer tool cURL. Alternatively, you could also test API requests / responses using a Chrome extension like Advanced REST Client or POSTMAN.

Versioning and Changes

Non-breaking changes: We will be adding new functionality and bug fixes to the API over time. You should expect to see new endpoints or new attributes for existing objects. Such changes will not result in a new API version. Please make sure that your code can handle new attributes gracefully. Also, please make sure your code does not depend on the order in which records are returned, unless it is explicitly stated in this documentation.

Breaking changes: We intend to maintain the current API version for the foreseeable future. If and when we decide to add functionality that breaks the contract of the current API, we will publish it with a new version number, so as to keep the existing API functionality backwards compatible.

Deprecations: Smartsheet occasionally deprecates APIs to indicate that those APIs should no longer be used in active development. Deprecated APIs typically remain present and usable for a reasonable period of time following the release in which they were deprecated, but may be removed entirely from a future version of the API. You should never use deprecated APIs in new development, and if you have existing code that uses deprecated APIs, we recommend that you update that code as soon as possible. For a list of Smartsheet API 2.0 deprecations, see Deprecations.

API Fundamentals

Authentication

The Smartsheet API utilizes OAuth 2.0 for Authentication and Authorization. An Authorization HTTP header containing an Access Token is required to authenticate requests. Access Tokens can be acquired in one of two ways:

User-generated Access Tokens

Smartsheet users can easily generate Access Tokens by logging in to their Smartsheet account. Once a token is generated, it can be used in a script or custom application, or with an API integration service like Zapier, to access any Smartsheet data which the token owner already can access in the application. See Direct API Access for more information on user-generated tokens.

Third-party Access Tokens

Third-party developers are able to build applications that can acquire Access Tokens using OAuth 2.0. See Third Party App Development for more information.

Access Levels

Throughout the API we have “Share” objects that represent the shared user’s access level. Also, on Sheets, Workspaces and Templates, there is an accessLevel attribute that describes the current user’s access level to that object. This corresponds directly to the sharing and access controls of Smartsheet that are available through the Smartsheet UI. The accessLevel attribute has one of the following values:

VIEWER The user has read-only access to the resource.
EDITOR The user can edit the resource, but cannot alter the structure of, delete or share the resource.
EDITOR_SHARE The same as EDITOR, but with the ability to share the resource to other users.
ADMIN The user can edit and share the resource, and can alter the structure of the resource as well.
OWNER The user has complete control over the resource.

Rate Limiting

In order to prevent abuse and undue stress on the Smartsheet servers, the API has a rate limiting feature that restricts users to 300 requests per minute per Access Token. Certain resource intensive operations, such as attaching a file and getting cell history, count as 10 requests to prevent abuse of these operations. We reserve the right to enforce this limit depending on the load on our systems. If and when the limit is enforced, any requests that exceed this limit will be rejected with an HTTP 503 error code, with the Smartsheet error code 4003. Please design your applications assuming that the stated limit will be enforced.

Errors

Standard HTTP Response codes are used to indicate success and error conditions. Generally, they will follow this pattern:

2xx Request was successful
4xx Problem with request (malformed or missing a parameter or access denied)
5xx Request was properly formatted, but the operation failed on Smartsheet’s end

Smartsheet HTTP codes:

200 OK
400 BAD REQUEST
401 NOT AUTHORIZED
403 FORBIDDEN
404 NOT FOUND
405 METHOD NOT SUPPORTED
500 INTERNAL SERVER ERROR
503 SERVICE UNAVAILABLE

All errors will also be accompanied by JSON-formatted error objects, containing a descriptive message. For example, doing a GET on a non-existent sheet at https://api.smartsheet.com/2.0/sheets/123456 will result in a response code of 404, indicating the resource was not found. The body of the response will include an Error object:

{
    “errorCode”: 1006,
    “message”: “Not Found”
}

The full list of error codes is below:

1001 An Access Token is required.
1002 Your Access Token is invalid.
1003 Your Access Token has expired.
1004 You are not authorized to perform this action.
1005 Single Sign-On is required for this account.
1006 Not Found.
1007 Version not supported.
1008 Unable to parse request. The following error occurred: {0}
1009 A required parameter is missing from your request: {0}.
1010 HTTP Method not supported.
1011 A required header was missing or invalid: {0}
1012 A required object attribute is missing from your request: {0}.
1013 The operation you are attempting to perform is not supported by your plan.
1014 There are no licenses available on your account.
1015 The user exists in another account. The user must be removed from that account before they can be added to yours.
1016 The user is already a member of your account.
1017 The user already has a paid account. The user must cancel that account before they can be added to yours.
1018 The value {0} was not valid for the parameter {1}.
1019 Cannot transfer to the user specified. User not found.
1020 User not found.
1021 Cannot transfer to the user specified. They are not a member of your account.
1022 Cannot delete the user specified. They are not a member of your account.
1023 The sheet specified is shared at the Workspace level.
1024 The HTTP request body is required for this Method.
1025 The share already exists.
1026 Transferring ownership is not currently supported.
1027 Share not found.
1028 You cannot edit the share of the owner.
1029 The parameter in the URI does not match the object in the request body.
1030 You are unable to assume the user specified.
1031 The value {0} was not valid for the attribute {1}.
1032 The attribute(s) {0} are not allowed for this operation.
1033 The template was not found.
1034 Invalid Row ID.
1035 Attachments and discussions cannot be POSTed with a row.
1036 The columnId {0} is invalid.
1037 The columnId {0} is included more than once in a single row.
1038 Invalid Cell value. Must be numeric or a string.
1039 Cannot edit a locked column {0}
1040 Cannot edit your own share.
1041 The value for {0} must be {1} characters in length or less, but was {2}.
1042 The value for cell in column {0}, {1}, did not conform to the strict requirements for type {2}.
1043 The row number you requested is blank and cannot be retrieved.
1044 Assume-User header is required for your Access Token.
1045 The resource specified is read-only.
1046 Cells containing formulas, links to other cells, system values, or Gantt values cannot be inserted or updated through the API.
1047 You cannot remove yourself from the account through the API.
1048 The user specified has declined the invitation to join your organization. You cannot modify declined invitations.
1049 You cannot remove admin permissions from yourself through the API.
1050 You cannot edit a locked row.
1051 Attachments of type FILE cannot be created using JSON.
1052 Invalid Accept header. Media type not supported.
1053 Unknown Paper size: {0}.
1054 The new sheet requires either a fromId or columns.
1055 One and only one column must be primary.
1056 Column titles must be unique.
1057 Primary columns must be of type TEXT_NUMBER.
1058 Column type of {1} does not support symbol of type {0}.
1059 Column options are not allowed when a symbol is specified.
1060 Column options are not allowed for column type {0}.
1061 Max count exceeded for field {0}.
1062 Invalid row location.
1063 Invalid parentId: {0}.
1064 Invalid siblingId: {0}.
1065 The column specified cannot be deleted.
1066 You can only share to {0} users at a time.
1067 Invalid client_id
1068 Unsupported grant type.
1069 Invalid Request. The authorization_code has expired.
1070 Invalid Request. Required parameter is missing: {0}.
1071 Invalid Grant. The authorization code or refresh token provided was invalid.
1072 Invalid hash value. The hash provided did not match the expected value.
1073 The redirect_uri did not match the expected value.
1074 You are trying to upload a file of {0}, but the API currently only supports {1}
1075 The Content-Size provided did not match the file uploaded. This may be due to network issues or because the wrong Content-Size was specified.
1076 The user has created sheets and must be added as a licensed user.
1077 Duplicate system column type: {0}.
1078 System column type {0} not supported for {1} {2}.
1079 Column type {0} is not supported for system column type {1}
1080 End Dates on dependency-enabled sheets cannot be created/updated. Please update either the Duration or Start Date column.
1081 You cannot delete another user’s discussions, comments, or comment attachments.
1082 You cannot add options to the given column {0} because it is not a PICKLIST.
1083 Auto number formatting cannot be added to a column {0}
1084 The auto number format is invalid.
1085 To change this column’s type you must first disable Dependencies for this sheet.
1086 Google was not able to verify your access.
1087 The column specified is used in a conditional formatting rule, so the column cannot be deleted and its type cannot be changed.
1088 Invalid length for concatenated auto number format. Concatenated format is {0}, with a length of {1}. Must be less than or equal to 40.
1089 The type specified is only used with System Columns.
1090 Column.type is required when changing symbol, systemColumnType or options.
1091 Invalid Content-Type: {0}
1092 You cannot delete this row. Either it or one or more of its children are locked.
1093 An error occurred verifying this receipt, please try again later.
1094 You cannot set a password on a new user unless they accept the license.
1095 The Excel file is invalid/corrupt. This may be due to an invalid file extension, an outdated Excel format, or an invalid Content-Length.
1096 This Apple payment receipt has already been applied to a user’s payment profile.
1097 A user must be a licensed sheet creator to be a resource viewer.
1098 To delete this column you must first disable Dependencies for this sheet.
1099 To delete this column you must first disable Resource Management for this sheet.
1100 Uploading new versions of a discussion comment attachment is not supported.
1101 Uploading new versions of non-FILE type attachments is not supported.
1102 A user must be a licensed sheet creator to be a group administrator.
1103 A group with the same name already exists.
1104 You must be a group administrator to create a group.
1105 The operation failed because one or more group members were not members of your account: {0}
1106 Group not found
1107 User specified in transferGroupsTo must be a group admin.
1108 transferGroupsTo must be provided because user being deleted owns one or more groups.
1109 Only one of cell.hyperlink or cell.linkInFromCell may be non-null.
1110 cell.value must be null if cell.linkInFromCell is non-null.
1111 Only one of cell.hyperlink.sheetId and cell.hyperlink.reportId may be non-null.
1112 cell.hyperlink.url must be null for sheet or report hyperlinks.
1113 cell.value must be a string when the cell is a hyperlink.
1114 Invalid sheetId or reportId: {0}
1115 Row must contain either cell link updates or row/cell value updates; mixing of both update types in one API call is not supported.
1116 You cannot link a cell to its own sheet.
1117 One of the following cell.hyperlink fields must be non-null: url, sheetId, or reportId.
1118 You cannot set the value of a Gantt allocation column (id {0}) in a row that has child rows.
1119 Failed to complete copy.
NOTE: may include a “detail” object containing “topContainerType” and “topContainerId” which represent the top-level folder or workspace that were partially copied.
1120 Too many sheets to copy.
NOTE: includes a “detail” object containing “maxSheetCount” which represents the server-side limit on the number of sheets allowed in a single folder/workspace copy operation.
1121 transferTo must be provided because user being deleted owns one or more groups.
1122 Requested URL does not support this method: {0}
1123 Specifying multiple row locations is not yet supported. Each row must use the same row location attribute and value (toBottom, toTop, parentId, siblingId, above)
1124 Invalid Content-Type header. Media type not supported.
1125 Each part in a multipart payload must have a name
1126 Multipart payload contained duplicate part names: {0}
1127 Required multipart part was missing: ’{0}’
1128 Multipart upload size limit exceeded.
1129 The resource you tried to create already exists.
1130 One of cell.value or objectValue may be set, but not both.
1131 cell.{0} for column {1} was of the wrong object type. Allowed types: {2}
1132 The token provided has previously been revoked.
1133 Column titles are not unique among input columns.
1134 Duplicate system column type among input columns.
1135 Input column index {0} is different from the first input column index {1}.
1136 Cannot copy or move row(s) within the same sheet.
1137 Input collection contains multiple instances of the same element.
1138 The user is not eligible for a trial organization.
1139 The user is an admin in another organization. Add ‘allowInviteAccountAdmin=true’ to the query string to invite their entire organization.
1140 The user must be added as a licensed user.
1141 Inviting users from an enterprise organization is not supported.
1142 Column type {0} is reserved for project sheets and may not be manually set on a column.
1143 To set {0}, you must first enable dependencies on the sheet.
1144 The user owns one or more groups and must be added as a Group Admin.
1145 Multipart upload request was invalid. Please check your request headers and payload.
1146 Unsupported operation: {0}.
1147 Multipart request contained an invalid part name: ’{0}’
2000 Invalid username and/or password.
2001 Your account is locked out.
2002 Invalid email address
2003 Your account is currently locked out due to a billing issue. Please contact Smartsheet Finance at finance@smartsheet.com.
2004 Your email address must be confirmed for you to log into Smartsheet. Please click on the link from your welcome mail, or you can confirm your email by resetting your password.
2005 The device id you have provided is longer than the maximum of 45 characters.
2006 The client id you have provided is not valid.
2008 Invalid login ticket.
2009 The given launch parameters are not currently supported by the API.
4000 An unexpected error has occurred. Please contact Smartsheet support at support@smartsheet.com for assistance.
4001 Smartsheet.com is currently offline for system maintenance. Please check back again shortly.
4002 Server timeout exceeded. Request has failed.
4003 Rate limit exceeded.
5xxx Errors in the 5xxx range represent conditions that a developer cannot reasonably prevent or handle, most typically related to account status. These error messages are localized and can be displayed to the end-user to inform them of the condition that caused the error to occur.

Column Types

Smartsheet supports the following standard column types, which are represented in a Column object with a type attribute set to one of the following:

Column Type Column.type Value Notes
Text/Number TEXT_NUMBER
Contact List CONTACT_LIST
Date DATE
Dropdown List PICKLIST Custom, RYG, Harvey Ball, Priority types, etc.
Checkbox CHECKBOX Checkbox, star, and flag types
Duration DURATION Only for dependency-enabled project sheets
This type can only be set through the Smartsheet application when configuring a project sheet.
Predecessor PREDECESSOR Only for dependency-enabled project sheets
This type can only be set through the Smartsheet application when configuring a project sheet.
Date/Time ABSTRACT_DATETIME Represents a project sheet’s Start and End dates.
Only for dependency-enabled project sheets
This type can only be set through the Smartsheet application when configuring a project sheet.

Symbol Columns

In addition to the basic column types above, the Smartsheet app also supports columns that display symbols. These are simply specialized columns of type PICKLIST or CHECKBOX, whose symbol attribute is set to one of the values below:

Symbols for CHECKBOX columns:

  • STAR
  • FLAG

Symbols for PICKLIST columns:

  • HARVEY_BALLS
  • PRIORITY
  • RYG
  • PRIORITY_HML
  • DECISION_SYMBOLS
  • DECISION_SHAPES
  • VCR
  • RYGB
  • RYGG
  • WEATHER
  • PROGRESS
  • ARROWS_3_WAY
  • ARROWS_4_WAY
  • ARROWS_5_WAY
  • DIRECTIONS_3_WAY
  • DIRECTIONS_4_WAY
  • SKI
  • SIGNAL
  • STAR_RATING
  • HEARTS
  • MONEY
  • EFFORT
  • PAIN

System Columns

In addition to the standard column types and symbols, Smartsheet has a number of system columns, which represent data that is filled in by Smartsheet and whose values cannot be changed by the user. These columns are represented with standard column types, with the Column.systemColumnType attribute set to one of the following:

Column.systemColumnType Value Column Type Notes
MODIFIED_DATE DATETIME
MODIFIED_BY CONTACT_LIST
CREATED_DATE DATETIME
CREATED_BY CONTACT_LIST
AUTO_NUMBER TEXT_NUMBER Columns of this system column type will include an AutoNumberFormat object that describes the mask used to generate the value.

Cell Values

Within the Smartsheet web application, all editable column types are flexible and cells in those columns can contain either a value specific to the column type (e.g. dates, checkboxes, symbols, etc.) or a free-form text value. This allows for a very flexible UI and is one of the key benefits to using Smartsheet.

Cell Value Representation

Cell objects retrieved through the Smartsheet API’s have two attributes representing cell values: Cell.value, and Cell.displayValue. An empty cell is always represented by null for both.

Cell.displayValue is always a string and is only returned for certain column types (see below). It represents the formatted value as it should be displayed to an end-user. For example, if a TEXT_NUMBER column is formatted as a US Dollar currency, its value may be a number like 1234.5678, but its displayValue would be “$1,234.57”.

Cell.value represents a cell’s raw value and can be one of the following primitive JSON types: string, number, or boolean, depending on the column type. Complex types are represented as strings, formatted as described below:

Column Type Possible Types for Cell.value Returns Cell.displayValue?
TEXT_NUMBER string: free-form text values
number: numeric values
Yes: same as value for strings; for number values, the number with formatting applied.
CONTACT_LIST string: an email address representing a contact, or a free-form text value. Yes: same as value for free-form strings; for contacts, the contact’s name if any, else their email address.
DATE string: a date in ISO-8601 format, or a free-form text value.
number: see Dates and Times for how to request dates to be returned as numbers.
No.
PICKLIST string: one of the picklist’s column options, or a free-form text value.
number: numeric values
Yes: same as value for strings; for number values, the number with formatting applied.
CHECKBOX boolean: true if the checkbox is checked, false otherwise.
string: a free-form text value.
No.
DURATION string: a duration value such as “4d 6h 30m” in the user’s locale, or a free-form text value.
See the Help Center for more information on durations.
Yes: same as value
PREDECESSOR string: a comma-delimited predecessor list such as “12FS +3d 4h, 14SS”, or a free-form text value.
See the Help Center for more information on predecessors.
Yes: same as value
ABSTRACT_DATETIME string: a project date and time in ISO-8601 format, or a free-form text value.
number: see Dates and Times for how to request dates to be returned as numbers.
No.

Cell Value Parsing

The flexibility in cell value data types is a powerful feature in the Smartsheet application, but at the same time, it poses a challenge for an API in terms of parsing. Being too flexible will likely result in unexpected behavior. For instance, if you write code to post a Date value to a Smartsheet and the API operation succeeds, you might assume that the date value you sent was interpreted as date. What happens if you posted your date in the wrong format? Do you really want Smartsheet to keep the malformed date as a Text value? Probably not.

To address this problem, the Smartsheet API employs a simple scheme to indicate whether you want a more predictable and strict interface or a more flexible one. By default, a cell value is expected to conform to “strict” rules for the type of the cell’s column. If an input value doesn’t conform, the API will return error code 1042.

If, however, you want the same flexibility as the Smartsheet web application, you can disable the strict rules, and we’ll do our best to make sense of it. To enable lenient parsing simply include "strict" : false in the Cell object in your request body.

The parsing rules for the various column types are as follows:

TEXT_NUMBER:

Strict All numeric and text values are valid and are interpreted literally.
Lenient All numeric and text values are valid. Formatted numbers passed as text values, such as currencies (“$5,000”), percentages (“50%”), or decimals (“100.5”) will be parsed to their numeric equivalents, based on the locale of the Access Token owner, with the proper formatting enabled for the cell.

PICKLIST:

Strict The value must be a string and must be one of the options for the Picklist.
Lenient All numeric and text values are valid. Formatted numbers will be parsed like TEXT_NUMBER formatted numbers.

DATE:

Strict The value must be a string value and a valid ISO 8601 date (YYYY-MM-DD).
Lenient We will attempt to convert the string value to date using ISO 8601 date format, as well as several locale-specific date formats. If the value is a parsable date format, we will recognize the date and store it as such. All other values are simply text values.

CONTACT_LIST:

Strict The value must be a valid email address. If “displayValue” is set, we use that as the name, otherwise if we find a match among the the Access Token owner’s contacts, we will associate this cell with that existing contact.
Lenient If the value is a valid email address, we handle it the same way as Strict. If not, we save the value as a text value.

CHECKBOX:

Strict Only boolean values (true or false) are valid.
Lenient Boolean values and string values of “true” and “false” are handled the same as Strict. All other values are saved as text values.

DURATION:

Strict Only valid duration strings in the user’s locale are valid. Information on duration strings can be found in the Help Center.
Lenient Numeric values are treated as duration values in days. String values which are valid duration strings in the user’s locale are treated as durations, and any other values are treated as free-form text values.

PREDECESSOR:

Strict Only valid predecessor strings in the user’s locale are valid. Information on predecessor strings can be found in the Help Center.
Lenient String values which are valid predecessor strings in the user’s locale are treated as predecessors, and any other values are treated as free-form text values.

ABSTRACT_DATETIME:

Strict The value must be a string value and a valid ISO 8601 date and time.
Lenient We will attempt to convert the string value to date using ISO 8601 date format, as well as several locale-specific date formats. If the value is a parsable date format, we will recognize the date and store it as such. All other values are simply text values.

Contact List Columns

With columns of type CONTACT_LIST, cells’ “value” and “displayValue” attributes are treated independently. The contact’s email address is represented by value, while the contact’s name (and the value displayed in the cell in the Smartsheet app) is represented by displayValue.

When creating or updating cells for a contact list column, the displayValue attribute works as follows:

  • If displayValue is non-null and non-empty, the Smartsheet cell will display the value provided.
  • If displayValue is an empty string, the Smartsheet cell will display the email address.
  • If displayValue is null or absent, Smartsheet will make a best guess effort at filling it in with a contact’s name based on the email address.

Paging

The Smartsheet API contains a number of index endpoints (typically denoted in the documentation with titles beginning with “Get All…” or “List…”) which return arrays of objects. Examples include GET /users, /sheets, /sheets/{sheetId}/columns, and many others. These endpoints all support pagination, meaning you can retrieve paged subsets of results, enabling you to process potentially large result sets in smaller chunks.

Paging Query String Parameters

Index endpoints all support pagination via the following optional query string parameters:

pageSize number The maximum number of items to return per page. Unless otherwise stated for a specific endpoint, defaults to 100 if not specified.
page number Which page to return. Defaults to 1 if not specified.
includeAll boolean If true, include all results (i.e. do not paginate). Mutually exclusive with pageSize and page (they are ignored if includeAll=true is specified).

Paged Responses

Index endpoints all return paged responses via an IndexResult object which provides paging metadata that can be used to navigate the full set of pages in the result set:

pageNumber number The current page in the full result set that the data array represents.
pageSize number The number of items in a page. Omitted if there is no limit to page size (and hence, all results are included). Unless otherwise specified, this defaults to 100 for most endpoints.
totalPages number The total number of pages in the full result set.
totalCount number The total number of items in the full result set.
data array An array of objects representing the current page of data in the result set.

Bulk-insert Operations

Several endpoints support optional bulk POST operations which exist alongside the standard single-object POST. For these endpoints, you may pass in either a single object, or an array of objects. Depending on what was passed in, the Result object returned will contain either a single object, or an array. An example optional bulk operation is POST /favorites: you can pass in a single Favorite object to create a single favorite, or an array of Favorite objects to create multiple favorites in a single request. Endpoints which support bulk operations will be noted as such in their API reference documentation.

NOTE: Several POST operations fail when attempting to create a single object which already exists (e.g. favorites, shares, group members). However, for the corresponding bulk operations, these endpoints will not return an error if one or more items in the array already exist. Existing items will simply be ignored, and Result object returned will omit them.

Dates and Times

The Smartsheet API returns all dates and times in the UTC time zone, in ISO-8601 format. If a date/time needs to be displayed to an end-user in their local time zone, you will need to do the conversion using the user’s time zone which you can obtain by getting the current user.

You can optionally choose to receive and input 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 flag works for any API request.

Getting Started

Developer Account

Developer accounts provide access to the full range of features and functionality available in production. They are easy to set up, will not expire, and will let you focus on your development without any risk to your production data.

To set up a Developer account, please visit the Smartsheet Developer Portal registration page. If you already have a paid Smartsheet account and your goal is to keep your development and production accounts separate, make sure to use a different email address when registering.

Please note that Developer accounts are intended for development and testing purposes only, and are subject to the Smartsheet Developer Program Agreement.

SDKs and Sample Code

See our Github repository for sample / source code in multiple languages and our tools and sample apps page for sample apps.

See our SDK page for available SDKs or to submit your vote for additional language coverage.

Direct API Access

Smartsheet makes it easy to directly access your data via the API. The first step is to generate an Access Token via the Smartsheet UI. Users can generate and have more than one active token at any time. Access Tokens generated in Smartsheet UI are long lived, meaning they won’t expire for 10 years. They are best used in system-level integrations, such as applications designed to keep Smartsheet and other systems in sync, or to integrate with Zapier, ifttt or similar API integration services.

Generating Access Token

These instructions assume that you already have an existing Smartsheet account. Follow these steps to generate an Access Token:

  1. Click the Account button in the upper-left corner of your Smartsheet screen and select Personal Settings. This will open the Personal Settings form.
  2. Click the API Access button to open the API Access form.
  3. Use the API Access form to generate new or manage existing acces tokens.

Because you can generate and have more than one active token at any time, you have the ability to implement a granular security policy by designating a separate token for each application or integration scenario you may have. That way, should any one token become compromised, you can easily revoke it without impacting any of your other API-enabled applications.

Using Access Tokens

Example Request:

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

Example Response:

{
    "email": "john.doe@smartsheet.com",
    "firstName": "John",
    "lastName": "Doe",
    "id": 48569348493401200
}

Once you have an Access Token, include it in the Authorization header for every request you make:

Authorization: Bearer 0da6cf0d848266b4cd32a6151b1

The header name is Authorization and the value of the header is Bearer ACCESS_TOKEN, where ACCESS_TOKEN is a token generated by you. Since the access token is being transmitted in clear text, all API calls are done over HTTPS.

Third Party App Development

In addition to being a powerful work management tool, Smartsheet is a powerful application platform. We are committed to making it easy to build applications on top of Smartsheet - whether you are developing a solution for your organization or creating an app for the Smartsheet customer community at large. We are here to support you and would love your feedback on how to improve the API and the developer experience.

As a developer, you may be building applications that allow any Smartsheet user to access his or her Smartsheet data. Doing so requires that you complete the following steps.

  1. Complete your Developer Profile
  2. Register your App
  3. Within your app, implement a 3-legged oAuth flow to obtain an access token that can be used to access Smartsheet data on behalf of an end user.

Developer Registration

Third party app registration and management is available via the Developer Tools. To get access to Developer Tools, you must first register as a Smartsheet developer. Follow the instructions on the registration form to add Developer Tools to an existing Smartsheet account or create a new Smartsheet developer account.

Once you complete the developer registration, log in to Smartsheet to access Developer Tools.

  1. Click the Account button in the upper-left corner of your Smartsheet screen.
  2. Now that you are registered as a Smartsheet developer, you should see a new Developer Tools option in the dropdown menu. Select it to open Developer Tools.
  3. Before you can register your first app, you will need to complete your developer profile. Developer profile is a public profile that anyone can access to learn more about you and your applications.
  4. Once your developer profile is complete, you will be able to use Developer Tools to register and manage your apps.

Registering Your App

To build a third party app, you must first register it with Smartsheet using Developer Tools:

  1. Login to Smartsheet.
  2. Click the Account button in the upper-left corner of your Smartsheet screen and select Developer Tools.
  3. Create new app and provide the required information, including name, description, contact info and a redirect URL. Redirect URL (also known as the “callback URL”) is the URL in your app where Smartsheet must redirect after authentication is complete.
  4. Use the generated app client id and secret to connect your app to Smartsheet. See oAuth Flow for details on how to use client id and secret to do that.

Access Scopes

In order to access an end user’s Smartsheet data, your application must explicitly ask for specific Access Scopes. The Access Scopes enable your app to communicate to the end users what type of operations it will be performing. Access Scopes do not override existing Access Level restrictions. For example, having the Access Scope of WRITE_SHEETS will not allow your app to update a sheet on which the end user has read-only permission.

The Access Scopes are as follows:

READ_SHEETS Read all sheet data, including comments, attachments and cell data
WRITE_SHEETS Insert and modify sheet data, including comments, attachments and cell data
SHARE_SHEETS Share sheets, including sending sheets as attachments
DELETE_SHEETS Delete sheets
CREATE_SHEETS Create new sheets
READ_USERS Retrieve users and groups for your Smartsheet organization
ADMIN_USERS Add and remove users from your Smartsheet organization; create groups and manage membership
ADMIN_SHEETS Modify sheet structure, including column definition, publish state, etc.
ADMIN_WORKSPACES Create and manage workspaces and folders, including sharing

oAuth Flow

Your app must implement a 3-legged oAuth flow to retrieve an access token that can be used to access Smartsheet data on behalf of an end user. This process involves the following steps:

  1. Request authorization from the user
  2. Obtain the authorization code
  3. Use the authorization code to obtain an access token
  4. Refresh the access token (as necessary)

Requesting authorization from the user

To request authorization from an end user, direct your user to https://www.smartsheet.com/b/authorize with the following parameters through either a GET or POST. The parameter values must be URL-encoded:

response_type
(required)
must be set to “code”
client_id
(required)
client id for your app
redirect_uri
(optional)
redirect URL you registered for your app (including protocol, e.g. “http://”); if not provided, the redirect URL set during registration is used
scope
(required)
space-delimited list of access scopes to which you are asking the user to grant access (note the spaces must be URL-encoded as “%20”)
state arbitrary string that will be returned to your app; intended to be used by you to ensure that this redirect is indeed from an OAuth flow that you initiated

Here is an example of a URL to which you would send your user as a GET request:

https://www.smartsheet.com/b/authorize?response_type=code&client_id=dheu3dmkd32fhxme&scope=READ_SHEETS%20WRITE_SHEETS&state=MY_STATE

If your user has not logged in to Smartsheet, he/she will first be directed to the Smartsheet login page. After a successful login, your user will be prompted to allow or deny the access scopes you requested.

Obtaining the authorization code

If the user clicks “Allow”, he/she will be redirected to the redirect_uri with the following parameters:

code authorization code required to obtain access token
expires_in number of seconds code is valid once issued; this is always 4 minutes - you must obtain an access token within that time
state state string specified earlier

If the user clicks “Deny”, he/she will be redirected to the redirect_uri with the following parameters:

error “access_denied”
state state string specified earlier

Other errors that may be returned include:

unsupported_response_type response_type must be set to “code”
invalid_scope one or more of the requested access scopes are invalid. Please check the list of access scopes

Obtaining an access token

Request an access token:

curl https://api.smartsheet.com/2.0/token \
-d 'grant_type=authorization_code&code={your_code}&client_id={your_client_id}&redirect_uri={redirect_uri}&hash={SHA_256(client_secret|code)}' \
-X POST

Successful Response:

{
   "access_token": "Access Token Value",
   "token_type": "bearer",
   "refresh_token": "Refresh Token Value",
   "expires_in": "# of seconds before token expires"
}

Error Response:

{
   "errorCode": "Smartsheet error number",
   "error": "OAuth error type",
   "error_description": "Error description"
}

Once you’ve successfully obtained an authorization code, the next step is to obtain an access token. To do so, you’ll need to make a POST request to https://api.smartsheet.com/2.0/token with the following parameters:

grant_type
(required)
must be set to “authorization_code”
client_id
(required)
client id for your app
code
(required)
authorization code returned in the previous step
redirect_uri
(optional)
redirect URL registered for your app, including the protocol (e.g., “http://”); if not provided, the redirect URL set during registration is used
hash
(required)
SHA-256 hash of your client secret concatenated with a pipe and the authorization code. The client_secret is never sent with the request.

Possible OAuth error types:

invalid_request The request parameters are invalid or missing.
invalid_client The client information is invalid. Ensure your client id is correct.
invalid_grant The authorization code or refresh token is invalid or expired, the redirect_uri does not match, or the hash value does not match the client secret and/or code.
unsupported_grant_type grant_type must equal “authorization_code” or “refresh_token”.

Refreshing an access token

Refresh an access token:

curl https://api.smartsheet.com/2.0/token \
-d 'grant_type=refresh_token&refresh_token={your_refresh_token}&client_id={your_client_id}&redirect_uri={redirect_uri}&hash={SHA_256(client_secret|refresh_token)}' \
-X POST

Successful Response:

{
   "access_token": "Newly refreshed Access Token",
   "expires_in": "# of seconds before token expires",
   "token_type": "bearer",
   "refresh_token": "New refresh token"
}

An access token is valid for one week but you can use the refresh token to obtain a new access token. Once you obtain the new access token, you can use it in place of the old one, which is no longer valid.

To do so, you’ll need to make a POST request to https://api.smartsheet.com/2.0/token with the following parameters:

grant_type
(required)
must be set to “refresh_token”
client_id
(required)
client id for your app
refresh_token
(required)
refresh_token value that came with the access token
redirect_uri
(optional)
redirect URL registered for your app, including the protocol (e.g., “http://”)
hash
(required)
SHA-256 hash of your client secret concatenated with a pipe and the refresh token value
Getting basic user info

Once you have obtained an access token on behalf of the user, you can fetch basic information (including user ID, name, etc.) about the caller using the Get Current User operation.

Admin Features

Smartsheet users with System Admin rights have access to additional API features, including user management and ability to access any sheet in the organization.

Manage Users

As an org Administrator, you can provision, de-provision and otherwise manage users in your Smartsheet organization. See Users for more information on relevant API calls.

Assume-User

As an org Administrator, you can assume the identity of any user in your organization. This advanced feature enables a number of useful business scenarios, such as executing an organization-wide backup or maintaining data attribution when integrating with another system.

Here is how it works. Simply add an Assume-User header to your call, with the URI-encoded email address of the user whose identity you want to assume as the value. For example, if you want to assume the identity of john.doe@smartsheet.com and john.doe@smartsheet.com is a confirmed member of your Smartsheet organization, you would add the following header:

Assume-User: john.doe%40smartsheet.com

You can then act on behalf of the user and make API calls as though you were that user.

Maintain Data Attribution

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Assume-User: bob.johnson%40smartsheet.com" \
-H "Content-Type: application/json" \
-X POST \
-d '{"toTop":true", "rows":[{"cells": [ {"columnId": 3738748463671172, "value": "Revision 1"}, {"columnId": 5427598323935108, "value": "New status", "strict": false} ]} ]}'

If you are integrating Smartsheet with another API-enabled system, such as Salesforce, it may be useful to maintain attribution when adding data to Smartsheet. For example, let’s say you want to add a new row to a Sales Pipeline sheet in Smartsheet whenever your sales team updates a sales pipeline in Salesforce. So, if Bob Johnson makes a change in Salesforce, wouldn’t it be great to make the new row show up in Smartsheet as if it were created by Bob? Specifying the Assume-User header API requests allows org Administrators to develop integrations which do just that.

List All Sheets

As an org Administrator, you can get a list of all sheets in your organization, regardless of ownership or whether or not the sheets have been shared to you. Please see List All Org Sheets for more information.

Backup All Org Data

Get list of all sheets in the org:

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

Fetch each sheet (using Assume-User):

curl https://api.smartsheet.com/2.0/sheets/{sheetId}?include=discussions,attachments \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Assume-User: OWNER_EMAIL"

Fetch each attachment:

curl -0 URL_TO_ATTACHMENT

To backup all of the org data, follow these steps:

  1. Get a list of all sheets in your organization.
  2. For each sheet in the list, fetch the sheet (optionally including a list of discussions and attachments) by assuming the identity of the owner of the sheet. (The value of the Assume-User header must be the URI-encoded email address of the sheet owner.)
  3. To backup all files attached to each sheet, fetch them one at a time, using your favorite download method. See Get Attachment for more information.

You can use the sheet version number to enable incremental backups. Fetch the sheet version number and compare it to the last backed up version number (you will need to store the sheet ID and the last backup up version number) - if they are the same, no need to include the sheet in your incremental backup run.

API Reference

Attachments

Attachments can exist on a Comment (i.e., within a Discussion), on a Row, or on a Sheet.

Objects

Attachment Object

id number Attachment ID
name string Attachment name
url string Attachment temporary URL (files only)
urlExpiresInMillis number Attachment temporary URL time to live (files only)
attachmentType string Attachment type (one of FILE, GOOGLE_DRIVE, LINK, BOX_COM, DROPBOX, or EVERNOTE)
attachmentSubType string Attachment sub type, only for GOOGLE_DRIVE type attachments; one of (DOCUMENT, SPREADSHEET, PRESENTATION, PDF, DRAWING)
createdAt timestamp A timestamp of when the attachment was originally added
createdBy User User object containing name and email of the creator of this attachment
mimeType string Attachment MIME type (PNG, etc.)
parentType string The type of object the attachment belongs to. One of “SHEET”, “ROW”, or “COMMENT”
parentId number The id of the parent
sizeInKb number The size of the file, if the attachmentType is FILE

Posting an Attachment

Like the Smartsheet web application, the Smartsheet API allows uploading files to Sheets, Rows and Comments. You can upload a file by performing either a simple upload or a multipart upload.

A simple upload allows you to add a single file attachment to the specified object. For example, you can perform a simple upload to upload a file to a sheet, row, or comment.

A multipart upload allows you to add a single file attachment to the specified object (i.e., attach a file to a sheet, row, or comment), or to create an object and attach a file using a single request. For example, you can perform a multipart upload to create a new Comment that contains a single file attachment or to add a new Discussion to a Sheet that contains a single file attachment.

Multipart Uploads

A multipart upload request allows you to add a single file attachment to the specified object (i.e., attach a file to a sheet, row, or comment), or to create an object and upload a file using a single request. For example, you can perform a multipart upload to create a new Comment that contains a single file attachment or to add a new Discussion to a Sheet that contains a single file attachment.

A multipart upload request must include the following HTTP headers:

Content-Type Must be set to multipart/form-data, and include the boundary string that will separate the parts in the request payload.
Content-Length The length of the request payload.

The request body of a multipart upload request contains one or more parts, each part containing either JSON or a file to upload. The request body must contain at least one part. Each part must start with the boundary string specified in the Content-Type request header, and must contain the following part headers:

Content-Disposition Contains the following semicolon-delimited items:
  • form-data
  • name=part name
  • filename=filename” (only required for file parts)
Content-Type The content type of the part: application/json for JSON objects, or the applicable MIME type for file parts

The last part in the request must be followed by the boundary string, followed by two hyphens.

The documentation for each operation that supports multipart uploads will specify the number and names of parts that are expected for the operation. File parts must have the part name “file”, and documentation for operations which allow for JSON object parts will specify the required part name for the JSON part.

The following example shows a multipart upload request that creates a Comment containing the specified text and file attachment:

POST https://api.smartsheet.com/2.0/sheets/4509093797881732/discussions/2889925487028100/comments
Authorization: Bearer ACCESS_TOKEN
Content-Length: 29008
Content-Type: multipart/form-data; boundary=----gU8h01zAAp3LagBr

------gU8h01zAAp3LagBr
Content-Disposition: form-data; name="comment"
Content-Type: application/json

{ "text": "Please review the attached image." }
------gU8h01zAAp3LagBr
Content-Disposition: form-data; name="file"; filename="picture.jpg"
Content-Type: image/jpeg

< Binary content for file >
------gU8h01zAAp3LagBr--

Simple Uploads

A simple upload allows you to add a single file attachment to the specified object. For example, you can perform a simple upload to upload a file to a sheet, row, or comment.

To perform this kind of upload, you must set specific headers to tell Smartsheet about the file. The following three headers are required:

Content-Disposition attachment to tell the API that a file is in the body of the POST request, followed by a semicolon, followed by filename= and the filename in quotes
Content-Type Can be left blank if it is not known (but must be present), and Smartsheet will make its best guess based on the extension of the file.
Content-Length Must be set to the size of the file, in bytes. For example to determine file size using in UNIX:

$ ls -l ProgressReport.docx
5463 ProgressReport.docx

The following example request shows a simple upload that adds a file attachment to a Sheet:

POST https://api.smartsheet.com/2.0/sheets/4509093797881732/attachments
Authorization: Bearer ACCESS_TOKEN
Content-Disposition: attachment; filename="ProgressReport.docx"
Content-Type: application/msword
Content-Length: 5463

< Binary content for file >

As shown in this example, the contents of the file is included in the body of the POST request. In most programming languages, this is done by reading the file from an input stream and writing it out to the output stream of the HTTP request.

Attach File to Comment

Example Request (multipart):

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/comments/{commentId}/attachments \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X POST \
-F "file=@ProgressReport.docx;type=application/msword"

Example Request (simple):

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/comments/{commentId}/attachments \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/msword" \
-H 'Content-Disposition: attachment; filename="ProgressReport.docx"' \
-H "Content-Length: FILE_SIZE" \
-X POST \
--data-binary @ProgressReport.docx

Example Response:

{
    "message": "SUCCESS",
    "result": {
        "attachmentType": "FILE",
        "createdAt": "2013-02-28T21:04:56-08:00",
        "id": 4583173393803140,
        "mimeType": "application/msword",
        "name": "ProgressReport.docx"
    },
    "resultCode": 0
}

POST /sheets/{sheetId}/comments/{commentId}/attachments

Attaches a file to the Comment. This operation can be performed using a simple upload or a multipart upload. For more information, see Posting an Attachment.

This operation will always create a new attachment. To upload a new version of the same attachment, use the Attach New Version operation.

Access Scope WRITE_SHEETS
Headers Required headers vary depending on the type of upload being performed (simple upload or multipart upload). See Posting an Attachment for details.
Request Body Request body varies depending on the type of upload being performed (simple upload or multipart upload). See Posting an Attachment for details.
Returns Result object containing an Attachment object for the newly created attachment

Attach File to Row

Example Request (multipart):

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/attachments \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X POST \
-F "file=@ProgressReport.docx;type=application/msword"

Example Request (simple):

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/attachments \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/msword" \
-H 'Content-Disposition: attachment; filename="ProgressReport.docx"' \
-H "Content-Length: FILE_SIZE" \
-X POST \
--data-binary @ProgressReport.docx

Example Response:

{
    "message": "SUCCESS",
    "result": {
        "attachmentType": "FILE",
        "createdAt": "2013-02-28T21:04:56-08:00",
        "id": 4583173393803140,
        "mimeType": "application/msword",
        "name": "ProgressReport.docx"
    },
    "resultCode": 0
}

POST /sheets/{sheetId}/rows/{rowId}/attachments

Attaches a file to the Row. This operation can be performed using a simple upload or a multipart upload. For more information, see Posting an Attachment.

This operation will always create a new attachment. To upload a new version of the same attachment, use the Attach New Version operation.

Access Scope WRITE_SHEETS
Headers Required headers vary depending on the type of upload being performed (simple upload or multipart upload). See Posting an Attachment for details.
Request Body Request body varies depending on the type of upload being performed (simple upload or multipart upload). See Posting an Attachment for details.
Returns Result object containing an Attachment object for the newly created attachment

Attach File to Sheet

Example Request (multipart):

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X POST \
-F "file=@ProgressReport.docx;type=application/msword"

Example Request (simple):

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/msword" \
-H 'Content-Disposition: attachment; filename="ProgressReport.docx"' \
-H "Content-Length: FILE_SIZE" \
-X POST \
--data-binary @ProgressReport.docx

Example Response:

{
    "message": "SUCCESS",
    "result": {
        "attachmentType": "FILE",
        "createdAt": "2013-02-28T21:04:56-08:00",
        "id": 4583173393803140,
        "mimeType": "application/msword",
        "name": "ProgressReport.docx"
    },
    "resultCode": 0
}

POST /sheets/{sheetId}/attachments

Attaches a file to the Sheet. This operation can be performed using a simple upload or a multipart upload. For more information, see Posting an Attachment.

This operation will always create a new attachment. To upload a new version of the same attachment, use the Attach New Version operation.

Access Scope WRITE_SHEETS
Headers Required headers vary depending on the type of upload being performed (simple upload or multipart upload). See Posting an Attachment for details.
Request Body Request body varies depending on the type of upload being performed (simple upload or multipart upload). See Posting an Attachment for details.
Returns Result object containing an Attachment object for the newly created attachment

Attach URL to Comment

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/comments/{commentId}/attachments \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name":"Search Engine", "description": "A popular search engine", "attachmentType":"LINK", "url":"http://www.google.com"}'

Example Response:

{
    "message": "SUCCESS",
    "result": {
        "attachmentType": "LINK",
        "createdAt": "2013-02-28T21:52:40-08:00",
        "description": "A popular search engine",
        "id": 1205473673275268,
        "name": "Search Engine",
        "url": "http://google.com"
    },
    "resultCode": 0
}

POST /sheets/{sheetId}/comments/{commentId}/attachments

Attaches a URL to the Comment.

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body Attachment object limited to the following attributes:
  • name
  • description (applicable when attaching to sheet or row only)
  • url
  • attachmentType
  • attachmentSubType
Returns Result object containing an Attachment object for the newly created attachment

The url can be any of the following:

  • a normal URL (attachmentType “LINK”)
  • a Google Drive URL (attachmentType “GOOGLE_DRIVE”)
  • a Box.com URL (attachmentType “BOX_COM”)
  • a Dropbox URL (attachmentType “DROPBOX”)
  • an Evernote URL (attachmentType “EVERNOTE”)

Attach URL to Row

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/attachments \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name":"Search Engine", "description": "A popular search engine", "attachmentType":"LINK", "url":"http://www.google.com"}'

Example Response:

{
    "message": "SUCCESS",
    "result": {
        "attachmentType": "LINK",
        "createdAt": "2013-02-28T21:52:40-08:00",
        "description": "A popular search engine",
        "id": 1205473673275268,
        "name": "Search Engine",
        "url": "http://google.com"
    },
    "resultCode": 0
}

POST /sheets/{sheetId}/rows/{rowId}/attachments

Attaches a URL to the Row.

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body Attachment object limited to the following attributes:
  • name
  • description (applicable when attaching to sheet or row only)
  • url
  • attachmentType
  • attachmentSubType
Returns Result object containing an Attachment object for the newly created attachment

The url can be any of the following:

  • a normal URL (attachmentType “LINK”)
  • a Google Drive URL (attachmentType “GOOGLE_DRIVE”)
  • a Box.com URL (attachmentType “BOX_COM”)
  • a Dropbox URL (attachmentType “DROPBOX”)
  • an Evernote URL (attachmentType “EVERNOTE”)

Attach URL to Sheet

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name":"Search Engine", "description": "A popular search engine", "attachmentType":"LINK", "url":"http://www.google.com"}'

Example Response:

{
    "message": "SUCCESS",
    "result": {
        "attachmentType": "LINK",
        "createdAt": "2013-02-28T21:52:40-08:00",
        "description": "A popular search engine",
        "id": 1205473673275268,
        "name": "Search Engine",
        "url": "http://google.com"
    },
    "resultCode": 0
}

POST /sheets/{sheetId}/attachments

Attaches a URL to the Sheet.

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body Attachment object limited to the following attributes:
  • name
  • description (applicable when attaching to sheet or row only)
  • url
  • attachmentType
  • attachmentSubType
Returns Result object containing an Attachment object for the newly created attachment

The url can be any of the following:

  • a normal URL (attachmentType “LINK”)
  • a Google Drive URL (attachmentType “GOOGLE_DRIVE”)
  • a Box.com URL (attachmentType “BOX_COM”)
  • a Dropbox URL (attachmentType “DROPBOX”)
  • an Evernote URL (attachmentType “EVERNOTE”)

Delete Attachment

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments/{attachmentId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE

Example Response:

{
    "message": "SUCCESS",
    "resultCode": 0
}

DELETE /sheets/{sheetId}/attachments/{attachmentId}

Deletes the Attachment specified in the URL.

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Returns Result object

Get Attachment

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments/{attachmentId} \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
    "name": "at3.png",
    "url": "URL_TO_ATTACHMENT",
    "attachmentType": "file",
    "mimeType": "image/png",
    "id": 4583173393803140,
    "urlExpiresInMillis": 120000
}

GET /sheets/{sheetId}/attachments/{attachmentId}

Fetches the Attachment specified in the URL.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Returns Attachment object. For File attachments, this will include a temporary URL for downloading the file.

Currently, the temporary URL is set to expire in 120000 milliseconds, or 2 minutes.

Get All Attachments

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 2,
    "data": [
        {
            "name": "att3.png",
            "attachmentType": "FILE",
            "mimeType": "image/png",
            "id": 4583173393803140,
            "parentType" : "SHEET",
            "parentId" : 341847495283
        },
        {
            "name": "att4.png",
            "attachmentType": "FILE",
            "mimeType": "image/png",
            "id": 4583173393803140,
            "parentType" : "ROW",
            "parentId" : 684956754834557
        }
    ]
}

GET /sheets/{sheetId}/attachments

Gets a list of all Attachments that are on the Sheet, including Sheet, Row, and Discussion level Attachments.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns IndexResult object containing an array of Attachment objects

Get Discussion Attachments

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions/{discussionId}/attachments \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 2,
    "data": [
        {
            "name": "att3.png",
            "attachmentType": "FILE",
            "mimeType": "image/png",
            "id": 4583173393803140,
            "parentType" : "COMMENT",
            "parentId" : 341847495283
        },
        {
            "name": "att4.png",
            "attachmentType": "FILE",
            "mimeType": "image/png",
            "id": 4583173393803140,
            "parentType" : "COMMENT",
            "parentId" : 684956754834557
        }
    ]
}

GET /sheets/{sheetId}/discussions/{discussionId}/attachments

Gets a list of all Attachments that are in the Discussion.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns IndexResult object containing an array of Attachment objects

Get Row Attachments

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/attachments \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 2,
    "data": [
        {
            "name": "att3.png",
            "attachmentType": "FILE",
            "mimeType": "image/png",
            "id": 4583173393803140,
            "parentType" : "ROW",
            "parentId" : 341847495283
        },
        {
            "name": "att4.png",
            "attachmentType": "FILE",
            "mimeType": "image/png",
            "id": 4583173393803140,
            "parentType" : "COMMENT",
            "parentId" : 684956754834557
        }
    ]
}

GET /sheets/{sheetId}/rows/{rowId}/attachments

Gets a list of all Attachments that are on the Row, including Row and Discussion level Attachments.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns IndexResult object containing an array of Attachment objects

Versioning

Attach New Version

Example Request (multipart):

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments/{attachmentId}/versions \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X POST \
-F "file=@ProgressReport.docx;type=application/msword"

Example Request (simple):

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments/{attachmentId}/versions \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/msword" \
-H 'Content-Disposition: attachment; filename="ProgressReport.docx"' \
-H "Content-Length: FILE_SIZE" \
-X POST \
--data-binary @ProgressReport.docx

Example Response:

{
    "message": "SUCCESS",
    "result": {
        "attachmentType": "FILE",
        "createdAt": "2013-02-28T21:04:56-08:00",
        "id": 4583173393803140,
        "mimeType": "application/msword",
        "name": "ProgressReport.docx"
    },
    "resultCode": 0
}

POST /sheets/{sheetId}/attachments/{attachmentId}/versions

Uploads a new version of a file to a Sheet or Row. This operation can be performed using a simple upload or a multipart upload. For more information, see Posting an Attachment.

Access Scope WRITE_SHEETS
Headers Required headers vary depending on the type of upload being performed (simple upload or multipart upload). See Posting an Attachment for details.
Request Body Request body varies depending on the type of upload being performed (simple upload or multipart upload). See Posting an Attachment for details.
Returns Result object containing an Attachment object for the newly created attachment

Delete All Versions

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments/{attachmentId}/versions \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE

Example Response:

{
    "message": "SUCCESS",
    "resultCode": 0
}

DELETE /sheets/{sheetId}/attachments/{attachmentId}/versions

Deletes all versions of the attachment corresponding to the specified Attachment ID. For attachments with multiple versions, this will effectively delete the attachment from the object that it’s attached to.

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Returns Result object

List All Versions

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments/{attachmentId}/versions \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 2,
    "data": [
        {
            "id": 4583173393803140,
            "name": "at3.png",
            "attachmentType": "file",
            "mimeType": "image/png",
            "createdAt": "2014-03-28T18:13:20-07:00"
        },
        {
            "id": 642523719853956,
            "name": "at3.png",
            "attachmentType": "file",
            "mimeType": "image/png",
            "createdAt": "2014-03-27T18:11:11-07:00"
        }
    ]
}

GET /sheets/{sheetId}/attachments/{attachmentId}/versions

Gets a list of all versions of the given Attachment ID, in order from newest to oldest.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns IndexResult object containing an array of Attachment objects

Cells

A collection of Cells comprises each Row in a Sheet.

Objects

Cell Object

columnId number The ID of the column that the cell is located in
columnType string See type definition on the Column object.
Only returned if the include query string parameter contains columnType.
value string,
number,
or boolean
A string, a number or a boolean value – depending on the cell type and the data in the cell. See Cell Values.
displayValue string Visual representation of cell contents, as presented to the user in the UI. See Cell Values.
formula string The formula for a cell, if set
hyperlink Hyperlink A hyperlink to a URL, sheet, or report
linkInFromCell CellLink An inbound link from a cell in another sheet. This cell’s value mirrors the linked cell’s value.
linksOutToCells CellLink[] An array of CellLink objects. Zero or more outbound links from this cell to cells in other sheets whose values mirror this cell’s value.
format string The format descriptor (see Formatting)
Only returned if the include query string parameter contains format and this cell has a non-default format applied.
conditionalFormat string The format descriptor describing this cell’s conditional format (see Formatting).
Only returned if the include query string parameter contains format and this cell has a conditional format applied.
strict boolean Set to false to enable lenient parsing. Defaults to true. This attribute can be specified in a request, but will never be present in a response. See Cell Value Parsing for more information about using this attribute.

Cell History Object

Extends the Cell object.

modifiedAt timestamp The datetime for when the change was made to the cell
modifiedBy User User object containing the name and email of the User that made the change

Represents a link to a Cell in a different Sheet.

status string One of the following values:
  • OK: the link is in a good state
  • BROKEN: the row or sheet linked to was deleted
  • INACCESSIBLE: the sheet linked to cannot be viewed by this user
  • Several other values indicating unusual error conditions: NOT_SHARED, BLOCKED, CIRCULAR, INVALID, and DISABLED.
sheetId number Sheet ID of the sheet that the linked cell belongs to
rowId number Row ID of the linked cell
columnId number Column ID of the linked cell
sheetName string Sheet name of the linked cell

Represents a hyperlink to a URL, a Sheet, or a Report.

url string When the hyperlink is a URL link, this property will contain the URL value.

When the hyperlink is a Sheet/Report link (i.e. sheetId or reportId is non-null), this property will contain the permalink to the Sheet or Report.
sheetId number If non-null, this hyperlink is a link to the Sheet with this ID.
reportId number If non-null, this hyperlink is a link to the Report with this ID.

Get Cell History

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/columns/{columnId}/history?include=columnType \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 3,
    "data": [
        {
            "columnId":642523719853956,
            "displayValue": "Revision 3",
            "columnType": "TEXT_NUMBER",
            "value": "Revision 3",
            "modifiedAt": "2013-06-24T00:10:18Z",
            "modifiedBy" : {
                "name" : "Jane Smart",
                "email" : "jane.smart@smartsheet.com"
            }
        },
        {
            "columnId":642523719853956,
            "displayValue": "Revision 2",
            "columnType": "TEXT_NUMBER",
            "value": "Revision 2",
            "modifiedAt": "2013-06-23T00:10:18Z",
            "modifiedBy" : {
                "name" : "Joe Smart",
                "email" : "joe.smart@smartsheet.com"
            }
        },
        {
            "columnId":642523719853956,
            "displayValue": "Revision 1",
            "columnType": "TEXT_NUMBER",
            "value": "Revision 1",
            "modifiedAt": "2013-06-22T00:10:18Z",
            "modifiedBy" : {
                "name" : "Joe Smart",
                "email" : "joe.smart@smartsheet.com" 
            }
        }
    ]
}

GET /sheets/{sheetId}/rows/{rowId}/columns/{columnId}/history

Gets the cell modification history.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters include (optional): when specified with a value of “columnType”, response will include the columnType attribute for each cell
This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns IndexResult object containing an array of Cell History objects

Update Cell(s)

To update the Cells in a Sheet, use the Update Row(s) operation.

You can create and modify cell links by using any API operation that creates or updates cell data. Creating or updating cell links via the cell.linkInFromCell attribute is a special operation. A given row or cell update operation may contain only link updates, or no link updates. Attempting to mix row/cell updates with cell link updates will result in error code 1115.

When creating a cell link, cell.value must be null (the data will be pulled from the linked cell).

A cell may not contain both a hyperlink and a cell link, so hyperlink and linkInFromCell may never both be non-null at the same time.

A cell link can only be added to an existing cell, so the cell.linkInFromCell attribute is not allowed when POSTing a new row to a sheet.

You can create and modify hyperlinks by using any API operation that creates or updates cell data. When creating or updating a hyperlink, cell.value may be set to a string value or null. If null, the cell’s value will be derived from the hyperlink:

  • If the hyperlink is a URL link, the cell’s value will be set to the URL itself.
  • If the hyperlink is a sheet or report link, the cell’s value will be set to the sheet or report’s name.

Columns

A Column is a component of a Sheet or Report.

Objects

Column Object

id number Column ID
index number Column index
title string Column title
primary boolean Returned only if the column is the Primary Column (value = “true”)
type string One of:
  • TEXT_NUMBER
  • DATE
  • DATETIME
  • CONTACT_LIST
  • CHECKBOX
  • PICKLIST
  • DURATION
  • PREDECESSOR
  • ABSTRACT_DATETIME
See Column Types.
options string[] Array of the options available for the column
hidden boolean Flag indicating whether the column is hidden
symbol string When applicable for CHECKBOX column type:
  • STAR
  • FLAG
When applicable for PICKLIST column type:
  • HARVEY_BALLS
  • PRIORITY
  • RYG
  • PRIORITY_HML
  • DECISION_SYMBOLS
  • DECISION_SHAPES
  • VCR
  • RYGB
  • RYGG
  • WEATHER
  • PROGRESS
  • ARROWS_3_WAY
  • ARROWS_4_WAY
  • ARROWS_5_WAY
  • DIRECTIONS_3_WAY
  • DIRECTIONS_4_WAY
  • SKI
  • SIGNAL
  • STAR_RATING
  • HEARTS
  • MONEY
  • EFFORT
  • PAIN
See Symbol Columns.
systemColumnType string When applicable, one of:
  • AUTO_NUMBER
  • MODIFIED_DATE
  • MODIFIED_BY
  • CREATED_DATE
  • CREATED_BY
See System Columns.
autoNumberFormat AutoNumberFormat Present when systemColumnType == AUTO_NUMBER
tags string[] Set of tags to indicate special columns, one of:
  • CALENDAR_START_DATE
  • CALENDAR_END_DATE
  • GANTT_START_DATE
  • GANTT_END_DATE
  • GANTT_PERCENT_COMPLETE
  • GANTT_DISPLAY_LABEL
  • GANTT_PREDECESSOR
  • GANTT_DURATION
  • GANTT_ASSIGNED_RESOURCE
width number Display width of the column in pixels
format string The format descriptor (see Formatting)
Only returned if the include query string parameter contains format and this column has a non-default format applied to it.
filter Filter The filter applied to the column.
Only returned if the include query string parameter contains filters and this column has a filter applied to it.

Criteria Object

operator string One of the following values:
  • EQUAL
  • NOT_EQUAL
  • GREATER_THAN
  • LESS_THAN
  • CONTAINS
  • BETWEEN
  • TODAY
  • PAST
  • FUTURE
  • LAST_N_DAYS
  • NEXT_N_DAYS
  • IS_BLANK
  • IS_NOT_BLANK
  • IS_NUMBER
  • IS_NOT_NUMBER
  • IS_DATE
  • IS_NOT_DATE
  • IS_CHECKED
  • IS_NOT_CHECKED
value1 string or number Optional. Present if a custom filter criteria’s operator has one or more arguments.
value2 string or number Optional. Present if a custom filter criteria’s operator has two arguments.

Filter Object

Smartsheet users can define and save personal column filters on sheets they can view. When any API operation that returns columns is invoked with the “include=filters” query string parameter, the column will include any active filters the user has defined for the sheet.

type string One of the following values:
  • LIST
  • CUSTOM
excludeSelected boolean If true, rows containing cells matching the “values” or “criteria” items are excluded instead of included.
values object[] containing strings, numbers, and booleans Only included if the filter is of type LIST.

An array of literal cell values that this filter will match against row cells in this column. The type of the objects in the array depend on the type of the cell values selected to be filtered on when the filter was created. These may be strings, numbers, booleans, or dates.
criteria Criteria[] Only included if the filter is of type CUSTOM.

An array of Criteria objects specifying custom criteria against which to match cell values.

Add Column(s)

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/columns \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '[{"title": "New Picklist Column 1", "type": "PICKLIST", "options": ["First", "Second", "Third"], "index": 4} , {"title":"New Date Column", "type":"DATE", "index":5}, {"title": "New Picklist Column 2", "type": "PICKLIST", "options": ["1", "2", "3"], "index": 6}]'

Example Response:

{
    "resultCode": 0,
    "result": [
        {
            "id": 9007194052434043,
            "index": 4,
            "title": "New Picklist Column 1",
            "type": "PICKLIST",
            "options": [
                "First",
                "Second",
                "Third"
            ],
            "width": 150
        },
        {
            "id": 4503594425063547,
            "index": 5,
            "title": "New Date Column",
            "type": "DATE",
            "width": 150
        },
        {
            "id": 6755394238748795,
            "index": 6,
            "title": "New Picklist Column 2",
            "type": "PICKLIST",
            "options": [
                "1",
                "2",
                "3"
            ],
            "width": 150
        }
    ],
    "message": "SUCCESS"
}

POST /sheets/{sheetId}/columns

Inserts one or more columns into the Sheet specified in the URL.

Access Scope ADMIN_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body Column object or an array of Column objects, with the following attributes:
  • title
  • type
  • symbol (optional)
  • options (optional)
  • index (zero-based)
  • systemColumnType (optional)
  • autoNumberFormat (optional)
  • width (optional)
Returns Result object containing the the newly created column(s) – either a single Column object or an array of Column objects, corresponding to what was specified in the request.

Delete Column

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/columns/{columnId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE

Example Response:

{
    "message": "SUCCESS",
    "resultCode": 0
}

DELETE /sheets/{sheetId}/columns/{columnId}

Deletes the Column specified in the URL.

Access Scope ADMIN_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Returns Result object

Get Column

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/columns/{columnId} \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
    "id": 7960873114331012,
    "index": 2,
    "symbol": "STAR",
    "title": "Favorite",
    "type": "CHECKBOX"
}

GET /sheets/{sheetId}/columns/{columnId}

Gets the Column specified in the URL.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters include (optional): when specified with a value of “filters”, response will include the filter that the user has applied to the column (if any)
Returns Column object

Get All Columns

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/columns \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 3,
    "data": [
        {
            "id": 7960873114331012,
            "index": 0,
            "symbol": "STAR",
            "title": "Favorite",
            "type": "CHECKBOX"
        },
        {
            "id": 642523719853956,
            "index": 1,
            "primary": true,
            "title": "Primary Column",
            "type": "TEXT_NUMBER"
        },
        {
            "id": 5146123347224452,
            "index": 2,
            "title": "Status",
            "type": "PICKLIST"
        }
    ]
}

GET /sheets/{sheetId}/columns

Gets a list of all Columns belonging to the Sheet specified in the URL.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters include (optional): when specified with a value of “filters”, response will include the filter that the user has applied to each column (if any)

This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns IndexResult object containing an array of Column objects

Update Column

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/columns/{columnId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X PUT \
-d '{"title":"First Column","index":0, "type" : "PICKLIST", "options" :["One","Two"]}'

Example Response:

{
    "message": "SUCCESS",
    "result": {
        "id": 5005385858869124,
        "index": 0,
        "options" : ["One", "Two"],
        "title": "First Column",
        "type": "PICKLIST"
    },
    "resultCode": 0
}

PUT /sheets/{sheetId}/columns/{columnId}

Updates properties of the column, moves the column, and/or renames the column.

Notes:

  • You cannot change the type of a Primary column.
  • While dependencies are enabled on a sheet, you can’t change the type of any special calendar/Gantt columns.
  • If the column type is changed, all cells in the column will be converted to the new column type.
  • Type is optional when moving or renaming, but required when changing type or dropdown values.

    Access Scope ADMIN_SHEETS
    Headers Authorization: Bearer ACCESS_TOKEN
    Content-Type: application/json
    Request Body A Column object that contains the following attributes:
    • index (column’s new index in the sheet)
    • title
    • type (optional)
    • options (optional)
    • symbol (optional)
    • systemColumnType (optional)
    • autoNumberFormat (optional)
    • width (optional)
    • format (optional)
    Returns Result object containing the Column object that was modified

Comments

A Comment is a component of a Discussion. Each Discussion is composed of one or more Comments.

Objects

Comment Object

id number Comment ID
text string Comment body
createdBy User User object containing name and email of the Comment’s author
createdAt timestamp Time of creation
modifiedAt timestamp Time of last modification
attachments Attachment[] Array of Attachment objects
discussionId number (optional) Discussion ID

Add Comment

Example Request (without attachment):

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions/{discussionId}/comments \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{"text":"This is a new comment."}'

Example Request (with attachment):

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions/{discussionId}/comments \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X POST \
-F "comment=<comment.json;type=application/json" \
-F "file=@file_to_attach;type=application/octet-stream"

    #
    # Content of the comment.json file:
    #
    {
        "text":"This text is the body of the new comment"
    }

Example Response:

{
    "message": "SUCCESS",
    "result": {
        "createdAt": "2013-02-28T22:58:30-08:00",
        "createdBy": {
            "email": "john.doe@smartsheet.com",
            "name": "John Doe"
        },
        "id": 6834973207488388,
        "modifiedAt": "2013-02-28T22:58:30-08:00",
        "text": "This is a new comment."
    },
    "resultCode": 0
}

POST /sheets/{sheetId}/discussions/{discussionId}/comments

Adds a Comment to a Discussion.



Creating a Comment without an Attachment:

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body Comment object with the following attribute:
  • text
Returns Result object containing Comment object that was created



Creating a Comment with an Attachment:

Access Scope WRITE_SHEETS
Headers See Multipart Uploads for information about headers that are required for multipart requests.
Request Body Request body should contain parts with the following names:
  • comment: JSON Comment object with the following attribute:
    • text
  • file: (optional) file to attach to the new comment
See Multipart Uploads for more information on parts.
Returns Result object containing a Comment object for the newly created comment, which in turn contains an Attachment object for the attachment that was uploaded to the comment.

Delete Comment

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/comments/{commentId} \
-H "Authorization: Bearer ACCESS_TOKEN"\
-X 'DELETE'

Example Response:

{
   "resultCode": 0,
   "message" : "SUCCESS"
}

DELETE /sheets/{sheetId}/comments/{commentId}

Deletes the Comment specified in the URL.

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Returns Result object

Get Comment

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/comments/{id} \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
    "text": "This is a comment",
    "createdBy" : {"name": "John Doe", "email" : "john.doe@smartsheet.com"},
    "createdAt" : "2013-06-24T21:07:45Z",
    "modifiedAt" : "2013-06-24T21:07:45Z",
    "discussionId" : 48569348493469348,
    "id": 48569348493401200
}

GET /sheets/{sheetId}/comments/{commentId}

Gets the Comment specified in the URL.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Returns Comment object

A Comment can contain one or more Attachments.

Comment Attachments

For details about working with a Comment’s attachments, see Attachments.

Discussions

A Discussion is a collection of one or more Comments. A Discussion can exist on a Row or a Sheet.

Objects

Discussion Object

id number Discussion ID
title string Discussion title
comments Comment[] Array of Comment objects
commentAttachments Attachment[] Array of Attachment objects
parentId number ID of the directly associated row or sheet: present only when the direct association is not clear (see Get All Discussions)
parentType string “SHEET” or “ROW”: present only when the direct association is not clear (see Get All Discussions)
lastCommentedAt timestamp Time of most recent comment
lastCommentedUser User User object containing name and email of the author of the most recent Comment
createdBy User User object containing name and email of the creator of the Discussion
accessLevel string User’s permissions on the Discussion
readOnly boolean Flag to indicate if the User can modify the Discussion

Create Discussion on Row

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/discussions \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{"title": "This is a new discussion", "comment": {"text":"This text is the body of the first comment"}}'

Example Response:

{
    "message": "SUCCESS",
    "result": {
        "comments": [
            {
                "createdAt": "2013-02-28T22:00:56-08:00",
                "createdBy": {
                    "email": "jane.doev@smartsheet.com",
                    "name": "Jane Doe"
                },
                "id": 4583173393803140,
                "modifiedAt": "2013-02-28T22:00:56-08:00",
                "text": "This text is the body of the first comment"
            }
        ],
        "id": 4583173393803140,
        "title": "This is a new discussion"
    },
    "resultCode": 0
}

POST /sheets/{sheetId}/rows/{rowId}/discussions

Creates a new Discussion on a Row.

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body Discussion object with the following attributes:
Returns Result object containing Discussion object for the newly created Discussion

Create Discussion on Sheet

Example Request (without attachment):

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{
    "title": "This is a new discussion", 
    "comment": {
        "text":"This text is the body of the first comment"
    }
}'

Example Request (with attachment):

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X POST \
-F "discussion=<discussion.json;type=application/json" \
-F "file=@file_to_attach;type=application/octet-stream"

    #
    # Content of the discussion.json file:
    #
    {
        "title": "This is a new discussion with an attachment", 
        "comment": {
            "text":"This text is the body of the first comment"
        }
    }

Example Response:

{
    "message": "SUCCESS",
    "result": {
        "comments": [
            {
                "createdAt": "2013-02-28T22:00:56-08:00",
                "createdBy": {
                    "email": "jane.doev@smartsheet.com",
                    "name": "Jane Doe"
                },
                "id": 4583173393803140,
                "modifiedAt": "2013-02-28T22:00:56-08:00",
                "text": "This text is the body of the first comment"
            }
        ],
        "id": 4583173393803140,
        "title": "This is a new discussion"
    },
    "resultCode": 0
}

POST /sheets/{sheetId}/discussions

Creates a new Discussion on a Sheet.



Creating a Discussion without an Attachment:

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body Discussion object with the following attributes:
Returns Result object containing Discussion object for the newly created Discussion


Creating a Discussion with an Attachment:

Access Scope WRITE_SHEETS
Headers See Multipart Uploads for information about headers that are required for multipart requests.
Request Body Request body should contain parts with the following names:See Multipart Uploads for more information on parts.
Returns Result object containing a Discussion object for the newly created Discussion, which contains a Comment object for the initial discussion comment, which in turn contains an Attachment object for the attachment that was uploaded to the comment.

Delete Discussion

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions/{discussionId} \
-H "Authorization: Bearer ACCESS_TOKEN"\
-X 'DELETE'

Example Response:

{
   "resultCode": 0,
   "message" : "SUCCESS"
}

DELETE /sheets/{sheetId}/discussions/{discussionId}

Deletes the Discussion specified in the URL.

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Returns Result object

Get All Discussions

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions?include=comments,attachments \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 1,
    "data": [
        {
            "id": 3138415114905476,
            "title": "Lincoln",
            "comments": [
                {
                    "id": 7320407591151492,
                    "text": "16th President",
                    "createdBy": {
                        "name": "Test User",
                        "email": "tester@smartsheet.com"
                    },
                    "attachments": [
                        {
                            "id": 1055252897130372,
                            "name": "test.html",
                            "attachmentType": "FILE",
                            "mimeType": "text/html",
                            "sizeInKb": 13,
                            "createdBy": {
                                "name": "Test User",
                                "email": "tester@smartsheet.com"
                            },
                            "createdAt": "2015-01-12T18:23:02-08:00"
                        }
                    ],
                    "createdAt": "2015-01-12T18:23:02-08:00",
                    "modifiedAt": "2015-01-12T18:23:02-08:00"
                }
            ],
            "accessLevel": "OWNER",
            "parentType": "ROW",
            "parentId": 4508369022150532,
            "lastCommentedUser": {
                "name": "Test User",
                "email": "tester@smartsheet.com"
            },
            "createdBy": {
                "name": "Test User",
                "email": "tester@smartsheet.com"
            },
            "readOnly": false,
            "lastCommentedAt": "2015-01-12T18:23:02-08:00"
        }
    ]
}

GET /sheets/{sheetId}/discussions

Gets a list of all Discussions associated with the specified Sheet (both sheet-level discussions and row-level discussions).

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters include (optional) – a comma-separated list of optional elements to include in the response:
  • comments
  • attachments - effective only if comments is present, otherwise ignored
This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns IndexResult object containing an array of Discussion objects

Get Discussion

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions/{discussionId} \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
    "title": "This is a new discussion",
    "id": 2331373580117892,
    "comments": [
        {
            "id": 2331373580117892,
            "text": "This text is the body of the discussion",
            "createdBy": {
                "email": "john.doe@smartsheet.com"
            },
            "modifiedAt": "2012-07-25T00:02:42-07:00"
        }
    ]
}

GET /sheets/{sheetId}/discussions/{discussionId}

Gets the Discussion specified in the URL.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Returns Discussion object

Get Row Discussions

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/discussions?include=comments,attachments \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 1,
    "data": [
        {
            "id": 3138415114905476,
            "title": "Lincoln",
            "comments": [
                {
                    "id": 7320407591151492,
                    "text": "16th President",
                    "createdBy": {
                        "name": "Test User",
                        "email": "tester@smartsheet.com"
                    },
                    "attachments": [
                        {
                            "id": 1055252897130372,
                            "name": "test.html",
                            "attachmentType": "FILE",
                            "mimeType": "text/html",
                            "sizeInKb": 13,
                            "createdBy": {
                                "name": "Test User",
                                "email": "tester@smartsheet.com"
                            },
                            "createdAt": "2015-01-12T18:23:02-08:00"
                        }
                    ],
                    "createdAt": "2015-01-12T18:23:02-08:00",
                    "modifiedAt": "2015-01-12T18:23:02-08:00"
                }
            ],
            "accessLevel": "OWNER",
            "parentType": "ROW",
            "parentId": 4508369022150532,
            "lastCommentedUser": {
                "name": "Test User",
                "email": "tester@smartsheet.com"
            },
            "createdBy": {
                "name": "Test User",
                "email": "tester@smartsheet.com"
            },
            "readOnly": false,
            "lastCommentedAt": "2015-01-12T18:23:02-08:00"
        }
    ]
}

GET /sheets/{sheetId}/rows/{rowId}/discussions

Gets a list of all Discussions associated with the specified Row.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters include (optional) – a comma-separated list of optional elements to include in the response:
  • comments
  • attachments - effective only if comments is present, otherwise ignored
This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns IndexResult object containing an array of Discussion objects

A Discussion is a collection of one or more Comments, each of which may contain Attachments.

Discussion Attachments

For details about working with the attachments within a Discussion, see Attachments.

Discussion Comments

For details about working with a Discussion’s comments, see Comments.

Favorites

Smartsheet allows users to “star” sheets, reports, folders, workspaces, and other objects on their Home tab to mark them as favorites. These API operations allow you to access the user’s favorite API-supported objects, as well as create and delete favorites.

Objects

Favorite Object

type string One of:
  • workspace
  • folder
  • sheet
  • report
  • template
objectId number ID of the favorited item. If type is “template”, only private sheet-type template ID is allowed.

Add Favorite(s)

Example Request:

curl https://api.smartsheet.com/2.0/favorites \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '[{"type": "sheet", "objectId": 8400677765441412}]'

Example Response:

{
    "resultCode": 0,
    "result": [
        {
            "type": "sheet",
            "objectId": 8400677765441412
        }
    ],
    "message": "SUCCESS"
}

POST /favorites

Adds one or more items to the user’s list of Favorite items.

If called with a single Favorite object, and that favorite already exists, error code 1129 will be returned. If called with an array of Favorite objects, any objects specified in the array that are already marked as favorites will be ignored and omitted from the response.

Access Scope ADMIN_WORKSPACES
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body Favorite object or an array of Favorite objects, with the following attributes:
  • type
  • objectId
Returns Result object containing object(s) that were marked as favorites – either a single Favorite object or an array of Favorite objects, corresponding to what was specified in the request.

List Favorites

Example Request:

curl https://api.smartsheet.com/2.0/favorites \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 2,
    "data": [
        {
            "type": "sheet",
            "objectId": 5897312590423940
        },
        {
            "type": "folder",
            "objectId": 1493728255862660
        }
    ]
}

GET /favorites

Gets a list of all of the user’s Favorite items.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns IndexResult object containing an array of Favorite objects

Remove Favorite

Remove Favorite Folder

Example Request:

curl https://api.smartsheet.com/2.0/favorites/folder/{folderId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE

Example Response:

{
    "message": "SUCCESS",
    "resultCode": 0
}

DELETE /favorites/folder/{folderId}

Removes a single Folder from the user’s list of Favorite items.

Access Scope ADMIN_WORKSPACES
Headers Authorization: Bearer ACCESS_TOKEN
Returns Result object

Remove Favorite Report

Example Request:

curl https://api.smartsheet.com/2.0/favorites/report/{reportId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE

Example Response:

{
    "message": "SUCCESS",
    "resultCode": 0
}

DELETE /favorites/report/{reportId}

Removes a single Report from the user’s list of Favorite items.

Access Scope ADMIN_WORKSPACES
Headers Authorization: Bearer ACCESS_TOKEN
Returns Result object

Remove Favorite Sheet

Example Request:

curl https://api.smartsheet.com/2.0/favorites/sheet/{sheetId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE

Example Response:

{
    "message": "SUCCESS",
    "resultCode": 0
}

DELETE /favorites/sheet/{sheetId}

Removes a single Sheet from the user’s list of Favorite items.

Access Scope ADMIN_WORKSPACES
Headers Authorization: Bearer ACCESS_TOKEN
Returns Result object

Remove Favorite Workspace

Example Request:

curl https://api.smartsheet.com/2.0/favorites/workspace/{workspaceId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE

Example Response:

{
    "message": "SUCCESS",
    "resultCode": 0
}

DELETE /favorites/workspace/{workspaceId}

Removes a single Workspace from the user’s list of Favorite items.

Access Scope ADMIN_WORKSPACES
Headers Authorization: Bearer ACCESS_TOKEN
Returns Result object

Remove Favorite Template

Example Request:

curl https://api.smartsheet.com/2.0/favorites/template/{templateId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE

Example Response:

{
    "message": "SUCCESS",
    "resultCode": 0
}

DELETE /favorites/template/{templateId}

Removes a single Template from the user’s list of Favorite items.

Access Scope ADMIN_WORKSPACES
Headers Authorization: Bearer ACCESS_TOKEN
Returns Result object

Remove Favorites (in bulk)

Remove Favorite Folders

Example Request:

curl https://api.smartsheet.com/2.0/favorites/folder?objectIds={folderId1},{folderId2} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE

Example Response:

{
    "message": "SUCCESS",
    "resultCode": 0
}

DELETE /favorites/folder

Removes multiple Folders from the user’s list of Favorite items.

Access Scope ADMIN_WORKSPACES
Headers Authorization: Bearer ACCESS_TOKEN
Parameters objectIds (required): a comma-separated list of object IDs representing the items to remove from Favorites
Returns Result object

Remove Favorite Reports

Example Request:

curl https://api.smartsheet.com/2.0/favorites/report?objectIds={reportId1},{reportId2} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE

Example Response:

{
    "message": "SUCCESS",
    "resultCode": 0
}

DELETE /favorites/report

Removes multiple Reports from the user’s list of Favorite items.

Access Scope ADMIN_WORKSPACES
Headers Authorization: Bearer ACCESS_TOKEN
Parameters objectIds (required): a comma-separated list of object IDs representing the items to remove from Favorites
Returns Result object

Remove Favorite Sheets

Example Request:

curl https://api.smartsheet.com/2.0/favorites/sheet?objectIds={sheetId1},{sheetId2} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE

Example Response:

{
    "message": "SUCCESS",
    "resultCode": 0
}

DELETE /favorites/sheet

Removes multiple Sheets from the user’s list of Favorite items.

Access Scope ADMIN_WORKSPACES
Headers Authorization: Bearer ACCESS_TOKEN
Parameters objectIds (required): a comma-separated list of object IDs representing the items to remove from Favorites
Returns Result object

Remove Favorite Templates

Example Request:

curl https://api.smartsheet.com/2.0/favorites/template?objectIds={templateId1},{templateId2} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE

Example Response:

{
    "message": "SUCCESS",
    "resultCode": 0
}

DELETE /favorites/template

Removes multiple Templates from the user’s list of Favorite items.

Access Scope ADMIN_WORKSPACES
Headers Authorization: Bearer ACCESS_TOKEN
Parameters objectIds (required): a comma-separated list of object IDs representing the items to remove from Favorites
Returns Result object

Remove Favorite Workspaces

Example Request:

curl https://api.smartsheet.com/2.0/favorites/workspace?objectIds={workspaceId1},{workspaceId2} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE

Example Response:

{
    "message": "SUCCESS",
    "resultCode": 0
}

DELETE /favorites/workspace

Removes multiple Workspaces from the user’s list of Favorite items.

Access Scope ADMIN_WORKSPACES
Headers Authorization: Bearer ACCESS_TOKEN
Parameters objectIds (required): a comma-separated list of object IDs representing the items to remove from Favorites
Returns Result object

Folders

A Folder can exist in a user’s Sheets folder (Home), in a Folder, or in a Workspace.

Objects

Folder Object

id number Folder ID
name string Folder name
favorite boolean Returned only if the user has marked the Folder as a Favorite in their Home tab (value = “true”)
permalink string Direct URL to Folder
sheets Sheet[] Array of Sheet objects
folders Folder[] Array of Folder objects
reports Report[] Array of Report objects
templates Template[] Array of Template objects

Create Child Folder

A Folder can be created in the user’s Sheets folder (Home), in another Folder, or in a Workspace.

Create Folder

Example Request:

curl https://api.smartsheet.com/2.0/home/folders \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name": "New folder"}'

Example Response:

{
    "message": "SUCCESS",
    "result": {
        "id": 1486948649985924,
        "name": "New folder"
    },
    "resultCode": 0
}

POST /home/folders

Creates a Folder in the user’s Sheets folder (Home).

Access Scope ADMIN_WORKSPACES
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body Folder object, limited to the following attribute:
  • name (string) - required, need not be unique
Returns Result object containing a Folder object for the newly created Folder

Create Folder (Folder)

Example Request:

curl https://api.smartsheet.com/2.0/folders/{folderid}/folders \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name": "New folder"}'

Example Response:

{
    "message": "SUCCESS",
    "result": {
        "id": 1486948649985924,
        "name": "New folder"
    },
    "resultCode": 0
}

POST /folders/{folderid}/folders

Creates a Folder in the specified Folder.

Access Scope ADMIN_WORKSPACES
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body Folder object, limited to the following attribute:
  • name (string) - required, need not be unique
Returns Result object containing a Folder object for the newly created Folder

Create Folder (Workspace)

Example Request:

curl https://api.smartsheet.com/2.0/workspaces/{workspaceid}/folders \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name": "New folder"}'

Example Response:

{
    "message": "SUCCESS",
    "result": {
        "id": 1486948649985924,
        "name": "New folder"
    },
    "resultCode": 0
}

POST /workspaces/{workspaceid}/folders

Creates a Folder in the specified Workspace.

Access Scope ADMIN_WORKSPACES
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body Folder object, limited to the following attribute:
  • name (string) - required, need not be unique
Returns Result object containing a Folder object for the newly created Folder

Delete Folder

Example Request:

curl https://api.smartsheet.com/2.0/folders/{folderId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE

Example Response:

{
    "resultCode": 0,
    "message": "SUCCESS"
}

DELETE /folders/{folderId}

Deletes the Folder (and its contents) specified in the URL.

Access Scope ADMIN_WORKSPACES
Headers Authorization: Bearer ACCESS_TOKEN
Returns Result object

Get Folder

Example Request:

curl https://api.smartsheet.com/2.0/folders/{folderId} \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
    "id": 7116448184199044,
    "name": "Projects",
    "permalink": "https://https://app.smartsheet.com/b/home?lx=B0_lvAtnWygeMrWr4Rfoa",
    "sheets": [
        {
            "id": 4509918431602564,
            "name": "Project Timeline",
            "accessLevel": "OWNER",
            "permalink": "https://app.smartsheet.com/b/home?lx=uWicCItTmkbxJwpCfQ5wiwW"
        }
    ]
}

GET /folders/{folderId}

Gets the specified Folder (and lists its contents).

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters include (optional): when specified with a value of “source”, response will include the source for any sheet that was created from another sheet or template
Returns Folder object

Note: If no folders and/or sheets are present in the Folder, the corresponding attribute (e.g., “folders”, “sheets”) will not be present in the response.

List Child Folders

Top-level child Folders can be retrieved from the user’s Sheets folder (Home), from another Folder, or from a Workspace.

List Folders

Example Request:

curl https://api.smartsheet.com/2.0/home/folders \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json"

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 2,
    "data": [
        {
            "id": 7116448184199044,
            "name": "Folder 1",
            "permalink": "https://app.smartsheet.com/b/home?lx=9sljohj8jEXqvJIbTrK2Hb"
        },
        {
            "id": 7116448184188022,
            "name": "Folder 2",
            "permalink": "https://app.smartsheet.com/b/home?lx=xgDVrNNbi-O9XwINEpT5Er"
        }
    ]
}

GET /home/folders

Gets a list of the top-level child Folders within the user’s Sheets folder (Home).

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns IndexResult object containing an array of Folder objects, limited to the following attributes:
  • id
  • name
  • permalink

List Folders (Folder)

Example Request:

curl https://api.smartsheet.com/2.0/folders/{folderId}/folders \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json"

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 2,
    "data": [
        {
            "id": 7116448184199044,
            "name": "Folder 1",
            "permalink": "https://app.smartsheet.com/b/home?lx=9sljohj8jEXqvJIbTrK2Hb"
        },
        {
            "id": 7116448184188022,
            "name": "Folder 2",
            "permalink": "https://app.smartsheet.com/b/home?lx=xgDVrNNbi-O9XwINEpT5Er"
        }
    ]
}

GET /folders/{folderId}/folders

Gets a list of the top-level child Folders within the specified Folder.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns IndexResult object containing an array of Folder objects, limited to the following attributes:
  • id
  • name
  • permalink

List Folders (Workspace)

Example Request:

curl https://api.smartsheet.com/2.0/workspaces/{workspaceId}/folders \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json"

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 2,
    "data": [
        {
            "id": 7116448184199044,
            "name": "Folder 1",
            "permalink": "https://app.smartsheet.com/b/home?lx=9sljohj8jEXqvJIbTrK2Hb"
        },
        {
            "id": 7116448184188022,
            "name": "Folder 2",
            "permalink": "https://app.smartsheet.com/b/home?lx=xgDVrNNbi-O9XwINEpT5Er"
        }
    ]
}

GET /workspaces/{workspaceId}/folders

Gets a list of the top-level child Folders within the specified Workspace.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns IndexResult object containing an array of Folder objects, limited to the following attributes:
  • id
  • name
  • permalink

Update Folder

Example Request:

curl https://api.smartsheet.com/2.0/folders/{folderId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X PUT \
-d '{"name": "New name for folder"}'

Example Response:

{
    "message": "SUCCESS",
    "result": {
        "id": 1486948649985924,
        "name": "New name for folder"
    },
    "resultCode": 0
}

PUT /folders/{folderId}

Updates the Folder specified in the URL.

Access Scope ADMIN_WORKSPACES
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body Folder object, limited to the following required attribute:
  • name (string)
Name need not be unique.
Returns Result object containing the updated Folder object

Groups

A Group is a collection of Group Members.

Objects

Group Object

id number Group ID
name string Group name
description string Group description
owner string Group owner’s email address
ownerId number Group owner’s User ID
members GroupMember[] Array of GroupMember objects
createdAt timestamp Time of creation
modifiedAt timestamp Time of last modification

Create Group

Example Request:

curl https://api.smartsheet.com/2.0/groups \
-H "Authorization: Bearer ACCESS_TOKEN"
-H "Content-Type: application/json" \
-X POST \
-d '{ "name": "API-created Group", "description": "Group created via API", "members": [{ "email": "john.doe@smartsheet.com" }]}'

Example Response:

{
    "resultCode": 0,
    "result": {
        "id": 2331373580117892,
        "name": "API-created Group",
        "description": "Group created via API",
        "owner": "john.doe@smartsheet.com",
        "ownerId": 4583173393803140,
        "members": [
            {
                "id": 4583173393803140,
                "email": "john.doe@smartsheet.com",
                "firstName": "John",
                "lastName": "Doe",
                "name": "John Doe"
            }
        ],
        "createdAt": "2014-05-29T16:28:49-07:00",
        "modifiedAt": "2014-05-29T16:28:49-07:00"
    },
    "message": "SUCCESS"
}

POST /groups

Creates a new Group.

Access Scope ADMIN_USERS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body Group object, limited to the following attributes:
  • name (required) – must be unique within the organization
  • description (optional)
  • members (optional) – array of GroupMember objects, each limited to the following attribute:
    • email
Returns Result object, containing a Group object for the newly created Group

Delete Group

Example Request:

curl https://api.smartsheet.com/2.0/groups/{groupId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE

Example Response:

{
    "message": "SUCCESS",
    "resultCode": 0
}

DELETE /groups/{groupId}

Deletes the Group specified in the URL.

Access Scope ADMIN_USERS
Headers Authorization: Bearer ACCESS_TOKEN
Returns Result object

Get Group

Example Request:

curl https://api.smartsheet.com/2.0/groups/{groupId} \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
    "id": 4583173393803140,
    "name": "Group 1",
    "description": "My group",
    "owner": "john.doe@smartsheet.com",
    "ownerId": 2331373580117892,
    "members": [
        {
            "id": 2331373580117892,
            "email": "john.doe@smartsheet.com",
            "firstName": "John",
            "lastName": "Doe",
            "name": "John Doe"
        },
    ],
    "createdAt": "2014-05-29T14:41:35-07:00",
    "modifiedAt": "2014-05-29T14:41:35-07:00"
}

GET /groups/{groupId}

Gets the Group specified in the URL.

Access Scope READ_USERS
Headers Authorization: Bearer ACCESS_TOKEN
Returns Group object that includes the list of GroupMembers

List All Org Groups

Example Request:

curl https://api.smartsheet.com/2.0/groups \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 1,
    "data": [
        {
            "id": 4583173393803140,
            "name": "Group 1",
            "description": "My group",
            "owner": "john.doe@smartsheet.com",
            "ownerId": 2331373580117892,
            "createdAt": "2014-05-29T14:41:35-07:00",
            "modifiedAt": "2014-05-29T14:41:35-07:00"
        }
    ]
}

GET /groups

Gets the list of all Groups in an organization. To fetch the members of an individual group, use the Get Group operation.

Access Scope READ_USERS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns IndexResult object containing an array of Group objects

Update Group

Example Request:

curl https://api.smartsheet.com/2.0/groups/{groupId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X PUT \
-d '{ "name": "Renamed Group", "description": "Some new description" }'

Example Response:

{
    "resultCode": 0,
    "result": {
        "id": 2331373580117892,
        "name": "Renamed Group",
        "description": "Some new description",
        "owner": "john.doe@smartsheet.com",
        "ownerId": 4583173393803140,
        "createdAt": "2014-05-29T16:28:49-07:00",
        "modifiedAt": "2014-05-29T17:00:23-07:00"
    },
    "message": "SUCCESS"
}

PUT /groups/{groupId}

Updates the Group specified in the URL.

Access Scope ADMIN_USERS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body Group object, limited to the following attributes:
  • name (optional) – must be unique within the organization
  • description (optional)
  • ownerId (optional): ID of an admin User to whom the group ownership will be transferred
Returns Result object containing the Group object for the updated group

A Group is comprised of one or more members.

Members of a Group

For details about working with a Group’s members, see Group Members.

Group Members

A Group Member is a User that belongs to a Group.

Objects

GroupMember Object

id number Group Member’s User ID
email string Group Member’s email address
firstName string Group Member’s first name
lastName string Group Member’s last name
name string Group Member’s full name

Add Group Member(s)

Example Request:

curl https://api.smartsheet.com/2.0/groups/{groupId}/members \
-H "Authorization: Bearer ACCESS_TOKEN"
-H "Content-Type: application/json" \
-X POST \
-d '[{ "email": "jane.doe@smartsheet.com" }]'

Example Response:

{
    "resultCode": 0,
    "result": [
        {
            "id": 1539725208119172,
            "email": "jane.doe@smartsheet.com",
            "firstName": "Jane",
            "lastName": "Doe",
            "name": "Jane Doe"
        }
    ],
    "message": "SUCCESS"
}

POST /groups/{groupId}/members

Adds one or more members to a Group.

If called with a single GroupMember object, and that group member already exists, error code 1129 will be returned. If called with an array of GroupMember objects any users specified in the array that are already group members will be ignored and omitted from the response.

Access Scope ADMIN_USERS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body A single GroupMember object or an array of Group Member objects, limited to the following attribute:
  • email
Returns Result object containing the members added to the group – either a single group member or array of group member objects, corresponding to what was specified in the request.

Remove Group Member

Example Request:

curl https://api.smartsheet.com/2.0/groups/{groupId}/members/{userId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE

Example Response:

{
    "message": "SUCCESS",
    "resultCode": 0
}

DELETE /groups/{groupId}/members/{userId}

Removes a member from a Group.

Access Scope ADMIN_USERS
Headers Authorization: Bearer ACCESS_TOKEN
Returns Result object

Home

In the Smartsheet UI, the “Home” tab shows all objects a User has access to, including Sheets, Folders, Workspaces, Reports, and Templates.

Objects

Home Object

sheets Sheet[] Array of Sheet objects
folders Folder[] Array of Folder objects
reports Report[] Array of Report objects
templates Template[] Array of Template objects
workspaces Workspace[] Array of Workspace objects

List All Contents

Example Request:

curl https://api.smartsheet.com/2.0/home?include=source \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
    "folders": [
        {
            "id": 5709073300645764,
            "name": "folder 1",
            "permalink": "https://app.smartsheet.com/b/home?lx=Dsje3YKtpyZScrCX6Z1"
        }
    ],
    "sheets": [
        {
            "id": 4583173393803140,
            "name": "sheet 1",
            "accessLevel": "OWNER",
            "permalink": "https://app.smartsheet.com/b/home?lx=Dsje3YKtpyZScrCX6Za"
        },
        {
            "id": 2331373580117892,
            "name": "Copy of sheet 1",
            "accessLevel": "OWNER",
            "permalink": "https://app.smartsheet.com/b/home?lx=Dsje3YKtpyZScrCX6Zb",
            "source": {
                "id": 4583173393803140,
                "type": "sheet"
            }
        }
    ],
    "reports": [],
    "templates": [],
    "workspaces": []
}

GET /home

Gets a nested list of all Home objects, including Sheets, Workspaces, Folders, Reports, and Templates, as shown on the Home tab.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters include (optional) – when specified with a value of “source”, response will include the source for any sheet that was created from another sheet or template
Returns Home object, populated according to the include parameter

Home Folders

For details about working with Folders in the user’s Sheets folder (i.e., at the Home level), see Folders.

Home Sheets

For details about working with sheets in the user’s Sheets folder (i.e., at the Home level), see Sheets.

Reports

A Report is a filtered view of the data from one or more Sheets. Like a Sheet, a Report is comprised of Columns, Rows, and Cells, and may optionally contain Attachments and/or Discussions.

Objects

Report Object

Extends the Sheet object, adding the following:

sourceSheets Sheet[] Array of Sheet objects (without rows), representing the sheets that rows in the report originated from. Only included in the Get Report response if the include parameter specifies “sourceSheets”.

Report Cell Object

Extends the Cell object, adding the following:

virtualColumnId number The virtual ID of the cell’s column. This property refers to the cell’s parent column in the Report, while the columnId property refers to the cell’s parent column in its originating source Sheet.

Report Column Object

Extends the Column object, adding the following:

virtualId number The virtual ID of this report column
sheetNameColumn boolean Returned only for the special “Sheet Name” report column (value = “true”)

A report column is a “virtual” column, in that it appears identical to source sheet column(s), but is in fact a different column belonging to the report. Cells in the report refer to this column via their virtualColumnId attribute, and to their actual column from their source sheet via their columnId attribute.

Report Row Object

Extends the Row object, adding the following:

sheetId number The ID of the Sheet from which the Row originates

Get Report

Example Request:

curl https://api.smartsheet.com/2.0/reports/{reportId} \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
    "id": 4583173393803140,
    "name": "My Report",
    "totalRowCount": 4,
    "accessLevel": "OWNER",
    "permalink": "https://app.smartsheet.com/b/home?lx=pWNSDH9itjBXxBzFmyf-5w",
    "createdAt": "2012-07-24T18:22:29-07:00",
    "modifiedAt": "2012-07-24T18:30:52-07:00",
    "columns": [
        {
            "virtualId": 4583173393803140,
            "index": 0,
            "primary": true,
            "title": "Sheet Name",
            "type": "TEXT_NUMBER",
            "sheetNameColumn": true
        },
        {
            "virtualId": 2331373580117892,
            "index": 1,
            "title": "Status",
            "type": "TEXT_NUMBER"
        }
    ],
    "rows": [
        {
            "id": 1732835527681924,
            "sheetId": 1060338138408836,
            "rowNumber": 1,
            "expanded": true,
            "accessLevel": "OWNER",
            "createdAt": "2014-10-02T15:05:35-07:00",
            "modifiedAt": "2014-10-02T15:05:35-07:00",
            "cells": [
                {
                    "virtualColumnId": 4583173393803140,
                    "type": "TEXT_NUMBER",
                    "value": "My Sheet",
                    "displayValue": "My Sheet"
                },
                {
                    "columnId": 8467747974735748,
                    "virtualColumnId": 2331373580117892,
                    "type": "TEXT_NUMBER",
                    "value": "In Progress",
                    "displayValue": "In Progress"
                }
            ]
        }

    ]
}

GET /reports/{reportId}

Gets the Report, including one page of Rows, and optionally populated with Discussions, Attachments, and source Sheets.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters include (optional) – a comma-separated list of optional objects to include in the response:
  • discussions
  • attachments
  • format
  • sourceSheets
pageSize (optional): Number of rows per page. If not specified, the default value is 100. This operation can return a maximum of 500 rows per page.
page (optional): Which page number (1-based) to return. If not specified, the default value is 1. If a page number is specified that is greater than the number of total pages, the last page will be returned.
Returns Report object, populated according to the “include” parameter

Get Report as Excel / CSV

Example Request (Excel):

curl https://api.smartsheet.com/2.0/reports/{reportId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Accept: application/vnd.ms-excel" \
-o output.xls

Example Response:

See local file named "output.xls"

Example Request (CSV):

curl https://api.smartsheet.com/2.0/reports/{reportId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Accept: text/csv" \
-o output.csv

Example Response:

See local file named "output.csv"

GET /reports/{reportId}

Gets the Report in the format specified, based on the Report ID.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Accept – must be set to one of the following values:
  • application/vnd.ms-excel
  • text/csv
Parameters include (optional) – a comma-separated list of optional objects to include in the response:
  • discussions
  • attachments
  • format
  • sourceSheets
pageSize (optional): Number of rows per page. If not specified, the default value is 100. This operation can return a maximum of 500 rows per page.
page (optional): Which page number (1-based) to return. If not specified, the default value is 1. If a page number is specified that is greater than the number of total pages, the last page will be returned.
Returns The file in either Excel or CSV format, containing the Report data according to the include parameter.

List Reports

Example Request:

curl https://api.smartsheet.com/2.0/reports 
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
    "pageNumber": 1,
    "totalPages": 1,
    "totalCount": 2,
    "data": [
        {   
            "id": 6761305928427396,
            "name": "r1",
            "accessLevel": "OWNER",
            "permalink": "https://app.smartsheet.com/b/home?lx=zWThapjNSR8LxW_kTdxPhQ"
        },  
        {   
            "id": 4508956358928260,
            "name": "r2",
            "accessLevel": "OWNER",
            "permalink": "https://app.smartsheet.com/b/home?lx=33-Y5QkQw6ZNSoApMKntbw"
        }   
    ]   
}

GET /reports

Gets the list of all Reports that the User has access to, in alphabetical order, by name.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns IndexResult object containing an array of Report objects limited to the following attributes:
  • id
  • name
  • accessLevel
  • permalink

Send Report via Email

Example Request:

curl https://api.smartsheet.com/2.0/reports/{reportId}/emails \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{"sendTo" : [{"email": "john.doe@smartsheet.com"}, {"groupId": 2258118617917316}], "subject": "Check these rows out!", "message": "Here are the rows I mentioned in our meeting", "ccMe": false, "format": "PDF", formatDetails": {"paperSize": "A4"}}'

Example Response:

{
    "message": "SUCCESS",
    "resultCode": 0
}

POST /reports/{reportId}/emails

Sends the Report as a PDF attachment via email to the designated recipients.

Access Scope SHARE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body SheetEmail object
Returns Result object

Share Report

For details about Report sharing, see Report Sharing.

A Report is comprised of Columns, Rows, and Cells, and may optionally contain Attachments and/or Discussions.

Report Attachments

For details about working with a Report’s attachments, see Attachments.

Report Cells

For details about working with a Report’s cells, see Cells.

Report Columns

For details about working with a Report’s columns, see Columns.

Report Discussions

For details about working with a Report’s discussions, see Discussions.

Report Rows

For details about working with a Report’s rows, see Rows.

Rows

A Row is a component of a Sheet or Report. Each Row is composed of a collection of Cells, and may optionally contain Discussions and/or Attachments.

Objects

Row Object

id number Row ID
sheetId number Parent Sheet ID
rowNumber number Row number within the sheet (1-based - starts at 1)
parentId number If this is a child row, the ID of the parent row, else omitted from response
siblingId number The ID of the previous sibling row at the same hierarchical level of this row, if any, else omitted from response
version number Number that is incremented every time a sheet is modified
filteredOut boolean true if this row is filtered out by a column filter (and thus is not displayed in the Smartsheet app), false if the row is not filtered out.
Only returned if the include query string parameter contains filters.
inCriticalPath boolean Only returned, with a value of true, if the sheet is a project sheet with dependencies enabled and this row is in the critical path
locked boolean true if the row is locked by the sheet owner or the admin. Returned if the row is locked.
lockedForUser boolean true if the row is locked for the requesting user. Returned if the row is locked.
expanded boolean Flag to indicate if the row is expanded or collapsed
accessLevel string User’s permission level on the Sheet that contains the Row
format string Format descriptor (see Formatting).
Only returned if the include query string parameter contains format and this row has a non-default format applied.
conditionalFormat string Format descriptor describing this row’s conditional format (see Formatting)
Only returned if the include query string parameter contains format and this row has a conditional format applied.
createdAt timestamp Time of creation
modifiedAt timestamp Time of last modification
cells Cell[] Array of Cell objects belonging to the row
discussions Discussion[] Array of Discussion objects.
Only returned if the include query string parameter contains discussions.
attachments Attachment[] Array of Attachment objects.
Only returned if the include query string parameter contains attachments.
columns Column[] Array of Column objects.
Only returned if the Get Row include query string parameter contains columns.
toTop boolean Flag used to specify the location at which to create or move a row. Indicates that the row should be added to the top of the sheet. This attribute can be specified in a request, but will never be present in a response.
toBottom boolean Flag used to specify the location at which to create or move a row. Indicates that the row should be added to the bottom of the sheet, or, if used in conjunction with parentId, added as the last child of the parent. This attribute can be specified in a request, but will never be present in a response.
parentId number Flag used to specify the location at which to create or move a row. Indicates that the row should be added as the first child of this row. This attribute can be specified in a request, but will never be present in a response.
siblingId number Flag used to specify the location at which to create or move a row. Indicates that the row should be added as the next row at the same hierarchical level of this row. This attribute can be specified in a request, but will never be present in a response.
above boolean Flag used to specify the location at which to create or move a row. Optionally used in conjunction with siblingId with a value of true to indicate that the row should be added above the specified sibling row. This attribute can be specified in a request, but will never be present in a response.

CopyOrMoveRowDirective Object

rowIds number[] The IDs of the rows to move or copy from the source sheet
to CopyOrMoveRowDestination A CopyOrMoveRowDestination object that identifies the destination sheet

CopyOrMoveRowDestination Object

sheetId number ID of the destination sheet

CopyOrMoveRowResult Object

destinationSheetId number ID of the destination sheet
rowMappings RowMapping[] Array of RowMapping objects

RowMapping Object

from number Row ID in the source sheet
to number Row ID in the destination sheet

Add Row(s)

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '[{"toTop":true, "cells": [ {"columnId": 7960873114331012, "value": true}, {"columnId": 642523719853956, "value": "New status", "strict": false} ] }, {"toTop":true, "cells": [ {"columnId": 7960873114331012, "value": true}, {"columnId": 642523719853956, "value": "New status", "strict": false} ] }]'

Example Response:

{
    "message": "SUCCESS",
    "result": [
        {
            "id": 7670198317672324,
            "sheetId": 2331373580117892,
            "rowNumber": 1,
            "expanded": true,
            "createdAt": "2013-02-28T17:45:13-08:00",
            "modifiedAt": "2013-02-28T17:45:13-08:00",
            "cells": [
                {
                    "columnId": 7960873114331012,
                    "type": "CHECKBOX",
                    "value": true
                },
                {
                    "columnId": 642523719853956,
                    "displayValue": "New status",
                    "type": "TEXT_NUMBER",
                    "value": "New status"
                }
            ]
        },
        {
            "id": 2040698783459204,
            "sheetId": 2331373580117892,
            "rowNumber": 2,
            "expanded": true,
            "createdAt": "2013-02-28T17:45:13-08:00",
            "modifiedAt": "2013-02-28T17:45:13-08:00",
            "cells": [
                {
                    "columnId": 7960873114331012,
                    "type": "CHECKBOX",
                    "value": true
                },
                {
                    "columnId": 642523719853956,
                    "displayValue": "New status",
                    "type": "TEXT_NUMBER",
                    "value": "New status"
                }
            ]
        }
    ],
    "version": 14, 
    "resultCode": 0
}

POST /sheets/{sheetId}/rows

Inserts one or more rows into the Sheet specified in the URL.

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body Row object or an array of Row objects, with the following attributes:
  • A location specifier – one of the following attributes (optional):
    • toTop
    • toBottom
    • parentId
    • siblingId
    • above
  • format (optional)
  • expanded (optional)
  • A cells attribute set to an array of Cell objects. To insert an empty row, set the cells attribute to empty or null. Each Cell object may contain the following attributes:
    • columnId (required)
    • value (required)
    • strict (optional)
    • format (optional)
    • hyperlink (optional)
  • See Column Types and Update Cell(s) for more information.
  • See Contact List Columns for information on inserting cells for columns of type CONTACT_LIST.
Returns Result object containing the newly created row(s) – either a single Row object or array of Row objects, corresponding to what was specified in the request, as well as the new version of the Sheet.

Copy Row(s) to Another Sheet

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/copy \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{ "rowIds": [145417762563972, 8026717110462340], "to": {"sheetId": 2258256056870788} }'

Example Response:

{
    "destinationSheetId": 2258256056870788,
    "rowMappings": [
        {    
            "from": 145417762563972,
            "to": 4508365800925060
        },   
        {    
            "from": 8026717110462340,
            "to": 2256565987239812
        }    
    ]    
}

POST /sheets/{sheetId}/rows/copy

Copies Row(s) from the Sheet specified in the URL to (the bottom of) another sheet.

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Parameters include (optional) – comma-separated list of row elements to copy in addition to the cell data:
  • attachments
  • discussions
  • children - if specified, any child rows of the rows specified in the request will also be copied to the destination sheet, and parent-child relationships amongst rows will be preserved within the destination sheet; if not specified, only the rows specified in the request will be copied.
ignoreRowsNotFound (optional) – true or false: default is false. If set to true, specifying row Ids that do not exist within the source sheet will not cause an error response. If omitted or set to false, specifying row Ids that do not exist within the source sheet will cause an error response (and no rows will be copied).
Request Body CopyOrMoveRowDirective object
Returns CopyOrMoveRowResult object

Delete Row

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE

Example Response:

{
   "message": "SUCCESS",
   "resultCode": 0
}

DELETE /sheets/{sheetId}/rows/{rowId}

Deletes the Row specified in the URL.

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Returns Result object

Get Row

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}?include=discussions,attachments,columns,columnType \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
    "id": 2361756178769796,
    "sheetId": 4583173393803140,
    "rowNumber": 1,
    "expanded": true,
    "cells": [
        {
            "columnType": "TEXT_NUMBER",
            "value": "Revision 1",
            "displayValue": "Revision 1",
            "columnId": 4583173393803140
        },
        {
            "columnType": "PICKLIST",
            "value": "completed",
            "displayValue": "completed",
            "columnId": 2331373580117892
        }
    ],
    "createdAt": "2012-07-24T23:10:55-07:00",
    "modifiedAt": "2012-07-24T23:14:27-07:00"
}

GET /sheets/{sheetId}/rows/{rowId}

Gets the Row specified in the URL.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters include (optional) – comma-separated list of elements to include in the response.

See Row Include Flags.
Also supports the columns include flag, which will add a columns array that specifies all of the columns for the sheet. This enables you to have the full context of the cells in the row.

The filters include flag may be used in conjunction with columns to include the user’s column filters with the columns.
exclude (optional): when specified with a value of “nonexistentCells”, response will not include cells that have never contained any data
Returns Row object

Move Row(s) to Another Sheet

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/move \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{ "rowIds": [145417762563972, 8026717110462340], "to": {"sheetId": 2258256056870788} }'

Example Response:

{
    "destinationSheetId": 2258256056870788,
    "rowMappings": [
        {    
            "from": 145417762563972,
            "to": 4508365800925060
        },   
        {    
            "from": 8026717110462340,
            "to": 2256565987239812
        }    
    ]    
}

POST /sheets/{sheetId}/rows/move

Moves Row(s) from the Sheet specified in the URL to (the bottom of) another sheet.

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Parameters include (optional) – comma-separated list of row elements to move in addition to the cell data:
  • attachments
  • discussions
ignoreRowsNotFound (optional) – true or false: default is false. If set to true, specifying row Ids that do not exist within the source sheet will not cause an error response. If omitted or set to false, specifying row Ids that do not exist within the source sheet will cause an error response (and no rows will be moved).
Request Body CopyOrMoveRowDirective object
Returns CopyOrMoveRowResult object

Send Row via Email

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/emails \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{"sendTo" : [{"email": "john.doe@smartsheet.com"}, {"groupId": 2258118617917316}], "subject": "Check these rows out!", "message": "Here are the rows I mentioned in our meeting", "ccMe": false, "includeAttachments": "true", "includeDiscussions": "false"}'

Example Response:

{
    "message": "SUCCESS",
    "resultCode": 0
}

POST /sheets/{sheetId}/rows/{rowId}/emails

Sends a Row via email.

Access Scope SHARE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body RowEmail object
Returns Result object

Update Row(s)

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X PUT \
-d '[{"id": "6572427401553796", "cells": [{"columnId": 7518312134403972,"value": "new value"}, {"columnId": 1888812600190852,"value": "A"}]}, {"id": "2068827774183300", "cells": [{"columnId": 7518312134403972,"value": "desc_updated"}, {"columnId": 1888812600190852,"value": "B"}]}]'

Example Response:

{
    "message": "SUCCESS",
    "result": [
        {
            "id": 2068827774183300,
            "rowNumber": 2,
            "parentRowNumber": 1,
            "parentId": 4624744004773764,
            "expanded": true,
            "createdAt": "2015-01-09T11:41:55-08:00",
            "modifiedAt": "2015-02-23T15:36:07-08:00",
            "cells": [
                {
                    "columnId": 7518312134403972,
                    "type": "TEXT_NUMBER",
                    "value": "desc_updated",
                    "displayValue": "desc_updated"
                },
                {
                    "columnId": 1888812600190852,
                    "type": "PICKLIST",
                    "value": "B",
                    "displayValue": "B"
                },
                {
                    "columnId": 6392412227561348,
                    "type": "TEXT_NUMBER",
                    "value": 1,
                    "displayValue": "1"
                }
            ]
        },
        {
            "id": 6572427401553796,
            "rowNumber": 3,
            "parentRowNumber": 1,
            "parentId": 4624744004773764,
            "expanded": true,
            "createdAt": "2015-01-09T11:41:55-08:00",
            "modifiedAt": "2015-02-23T15:36:07-08:00",
            "cells": [
                {
                    "columnId": 7518312134403972,
                    "type": "TEXT_NUMBER",
                    "value": "new value",
                    "displayValue": "desc_updated"
                },
                {
                    "columnId": 1888812600190852,
                    "type": "PICKLIST",
                    "value": "A",
                    "displayValue": "A"
                },
                {
                    "columnId": 6392412227561348,
                    "type": "TEXT_NUMBER",
                    "value": 1,
                    "displayValue": "1"
                }
            ]
        }
    ],
    "version": 8,
    "resultCode": 0
}

PUT /sheets/{sheetId}/rows

Updates cell values in the specified row(s), expands/collapses the specified row(s), and/or modifies the position of specified rows (including indenting/outdenting).

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body Row object or an array of Row objects, with the following attributes:
  • expanded (optional)
  • format (optional)
  • A location specifier – one of the following attributes (optional): One of:
    • toTop: Moves the row (and its child rows, if any) to the top of the sheet.
    • toBottom: Moves the row (and its child rows, if any) to the bottom of the sheet
    • parentId: Moves the row (and its child rows, if any) as the first child row of the parent. toBottom = true can also be set to move the row as the last child of the parent
    • siblingId: Moves the row (and its child rows, if any) as the next sibling of the row ID provided
  • cells (optional) – if specified, must be an array of Cell objects, where each object is limited to the following attributes:
    • columnId (required)
    • value (required)
    • strict (optional)
    • format (optional)
    • hyperlink (optional) with exactly one of the following attributes set:
      • url
      • sheetId
      • reportId
    • linkInFromCell (optional) with all of the following attributes set:
      • sheetId
      • rowId
      • columnId
  • locked (optional) - true to lock the row or false to unlock the row.
See Column Types for more information.

Please note the following:
  • Column Ids must be valid for the sheet to which the row belongs, and must only be used once for each row in the operation.
  • Cells containing formulas cannot be updated.
  • Cells of a project sheet in the “Predecessor” or “Finish Date” columns cannot be updated at this time.
  • Max length for a cell value is 4000 characters after which truncation will occur without warning. Empty string values are converted to null.
Returns Result object containing the updated row(s) – either a single Row object or an array of Row objects, corresponding to what was specified in the request.

A Row is comprised of a collection of Cells, and may optionally contain Attachments and/or Discussions.

Row Attachments

For details about working with a Row’s attachments, see Attachments.

Row Cells

For details about working with a Row’s cells, see Cells.

Row Discussions

For details about working with a Row’s discussions, see Discussions.

Row Include Flags

Endpoints which return rows (e.g. get sheet, get row) support the optional include query string parameter. If specified, the value of the include parameter is a comma-delimited list of flags that indicate additional attributes to be included in each Row object within the response.

Include Flag Notes
discussions Includes row discussions array.
To include discussion attachments, both attachments and discussions must be present in the include list.
attachments Includes row attachments array.
To include discussion attachments, both attachments and discussions must be present in the include list.
format Includes format attribute on the row and its cells. See Formatting.
filters Includes filteredOut attribute indicating if the row should be displayed or hidden according to the sheet’s filters.
columnType Includes columnType attribute in the row’s cells indicating the type of the column the cell resides in.

Searching

Use the Search operations to search a specific Sheet or to search across all Sheets that a User can access.

Objects

SearchResult Object

totalCount number Total number of search results
results SearchResultItem[] Array of SearchResultItem objects

SearchResultItem Object

text string Search result text excerpt
objectId number Search result object ID
objectType string Search result object type (row, sheet, report, template, discussion, attachment)
parentObjectId number Search result parent object ID
parentObjectType string Search result parent object type (workspace, folder, sheet, report, template)
parentObjectName string Search result parent object name
contextData array Additional info on search result context (row num…)

Search Everything

Example Request:

curl https://api.smartsheet.com/2.0/search?query=stuff \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
    "results": [
        {
            "contextData": [
                "Discussion 1"
            ],
            "objectId": 1888207043356548,
            "objectType": "discussion",
            "parentObjectId": 7141187195824004,
            "parentObjectName": "Sheet 1",
            "parentObjectType": "sheet",
            "text": "discussion stuff goes here"
        },
        {
            "contextData": [
                "Row 1"
            ],
            "objectId": 2711817823774596,
            "objectType": "row",
            "parentObjectId": 2583735121012612,
            "parentObjectName": "Sheet 2",
            "parentObjectType": "sheet",
            "text": "row stuff goes here"
        }
    ],
    "totalCount": 2
}

GET /search

Searches all Sheets that the User can access, for the specified text.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters query (required): Text with which to perform the search.
Returns SearchResult object that contains a maximum of 100 SearchResultems

Search Sheet

Example Request:

curl https://api.smartsheet.com/2.0/search/sheets/{sheetId}?query=stuff \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
    "results": [
        {
            "contextData": [
                "Discussion 1"
            ],
            "objectId": 1888207043356548,
            "objectType": "discussion",
            "parentObjectId": 7141187195824004,
            "parentObjectName": "Sheet 1",
            "parentObjectType": "sheet",
            "text": "discussion stuff goes here"
        }
    ],
    "totalCount": 1
}

GET /search/sheets/{sheetId}

Searches a Sheet for the specified text.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters query (required): Text with which to perform the search.
Returns SearchResult object that contains a maximum of 100 SearchResultems

Sending via Email

Use the Send operations to send a Report, a Row, or a Sheet via email.

Objects

Email Object

sendTo Recipient[] Array of Recipient objects. Required.
subject string The subject of the email. Optional.
message string The message of the email. Optional.
ccMe boolean A flag to indicate whether or not to send a copy of the email to the sender. Optional, defaults to false.

FormatDetails Object

paperSize string One of the following values: LETTER, LEGAL, WIDE, ARCHD, A4, A3, A2, A1, A0.

Recipient Object

Specifies the recipient of an Email. The recipient may be either an individual or a group. To specify an individual, set the email attribute; to specify a group, set the groupId attribute. Either email and groupId may be set, but not both.

email string The email address of an individual recipient. Optional.
groupId number The ID of a group recipient. Optional.

RowEmail Object

Extends the Email object, adding the following:

includeAttachments boolean A flag to indicate whether or not to include Attachments in the email.
includeDiscussions boolean A flag to indicate whether or not to include Discussions in the email.

SheetEmail Object

Extends the Email object, adding the following:

format string Can either be “PDF” or “EXCEL”.
formatDetails FormatDetails A FormatDetails object.

Send Report

Example Request:

curl https://api.smartsheet.com/2.0/reports/{reportId}/emails \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{"sendTo" : [{"email": "john.doe@smartsheet.com"}, {"groupId": 2258118617917316}], "subject": "Check these rows out!", "message": "Here are the rows I mentioned in our meeting", "ccMe": false, "format": "PDF", formatDetails": {"paperSize": "A4"}}'

Example Response:

{
    "message": "SUCCESS",
    "resultCode": 0
}

POST /reports/{reportId}/emails

Sends the Report as a PDF attachment via email to the designated recipients.

Access Scope SHARE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body SheetEmail object
Returns Result object

Send Row

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/emails \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{"sendTo" : [{"email": "john.doe@smartsheet.com"}, {"groupId": 2258118617917316}], "subject": "Check these rows out!", "message": "Here are the rows I mentioned in our meeting", "ccMe": false, "includeAttachments": "true", "includeDiscussions": "false"}'

Example Response:

{
    "message": "SUCCESS",
    "resultCode": 0
}

POST /sheets/{sheetId}/rows/{rowId}/emails

Sends a Row via email.

Access Scope SHARE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body RowEmail object
Returns Result object

Send Sheet

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/emails \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{"sendTo" : [{"email": "john.doe@smartsheet.com"}, {"groupId": 2258118617917316}], "subject": "Check these rows out!", "message": "Here are the rows I mentioned in our meeting", "ccMe": false, "format": "PDF", formatDetails": {"paperSize": "A4"}}'

Example Response:

{
    "message": "SUCCESS",
    "resultCode": 0
}

POST /sheets/{sheetId}/emails

Sends the Sheet as a PDF attachment via email to the designated recipients.

Access Scope SHARE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body SheetEmail object
Returns Result object

Server Information

For developer convenience, the Smartsheet API provides access to application constants.

Objects

ServerInfo Object

supportedLocales array Array of strings representing all Smartsheet-supported locales.
formats FormatTables Definition of format tables that are used in Column, Row, and Cell format property. For more information, see Formatting.

Get Server Info

Example Request:

curl https://api.smartsheet.com/2.0/serverinfo

Example Response: (too long to list in its entirety)

{
        "supportedLocales": [  ],
        "formats": {  }
}

GET /serverinfo

Gets application constants.

Access Scope None required (may be called unauthenticated)
Headers None required (may be called unauthenticated)
Returns ServerInfo object

Sharing

Use the Sharing operations to control sharing of Reports, Sheets, and Workspaces.

Objects

Share Object

id number Share ID.
NOTE: unlike other Smartsheet object ids, this id is an alphanumeric string.
type string The type of this share. One of USER or GROUP.
userId number User ID if the share is a user share, else null.
groupId number Group ID if the share is a group share, else null.
email string User’s email address for user shares; null for group shares.
name string If a user share and user is also a contact, the user’s full name. If a group share, the group’s name.
accessLevel string User or group’s access level on shared object.
subject string The subject of the email that will optionally be sent to notify the recipient. This attribute can be specified in a request, but will never be present in a response.
message string The message to be included in the body of the email that will optionally be sent to the recipient. This attribute can be specified in a request, but will never be present in a response.
ccMe boolean Flag to indicate whether or not to send a copy of the email to the sharer of the sheet. This attribute can be specified in a request, but will never be present in a response.

Report Sharing

Delete Report Share

Example Request:

curl https://api.smartsheet.com/2.0/reports/{reportId}/shares/{shareId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE

Example Response:

{
    "message": "SUCCESS",
    "resultCode": 0
}

DELETE /reports/{reportId}/shares/{shareId}

Deletes the Share specified in the URL.

Access Scope SHARE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Returns Result object

Get Report Share

Example Request:

curl https://api.smartsheet.com/2.0/reports/{reportId}/shares/{shareId} \
-H "Authorization: Bearer ACCESS_TOKEN" 

Example Response:

{
    "id": "AQAISF82FOeE",
    "type": "GROUP",
    "groupId": 2331373580117892,
    "name": "Group 1",
    "accessLevel": "ADMIN"
}

GET /reports/{reportId}/shares/{shareId}

Gets the Share specified in the URL.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Returns Share object

List Report Shares

Example Request:

curl https://api.smartsheet.com/2.0/reports/{reportId}/shares \
-H "Authorization: Bearer ACCESS_TOKEN" 

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 2,
    "data": [
        {
            "id": "AAAQSF82FOeE",
            "type": "USER",
            "userId": 4583173393803140,
            "email": "john.doe@smartsheet.com",
            "name": "John Doe",
            "accessLevel": "OWNER"
        },
        {
            "id": "AQAISF82FOeE",
            "type": "GROUP",
            "groupId": 2331373580117892,
            "name": "Group 1",
            "accessLevel": "ADMIN"
        }
    ]
}

GET /reports/{reportId}/shares

Gets a list of all Users and Groups to whom the specified Report is shared, and their access level.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns IndexResult object containing an array of Share objects

Share Report

Example Request:

curl https://api.smartsheet.com/2.0/reports/{reportId}/shares?sendEmail=true \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '[{"email": "jane.doe@smartsheet.com", "accessLevel": "EDITOR"}]'

Example Response:

{
    "resultCode": 0,
    "result": [
        {
            "id": "AAAFeF82FOeE",
            "type": "USER",
            "userId": 1539725208119172,
            "email": "jane.doe@smartsheet.com",
            "name": "Jane Doe",
            "accessLevel": "EDITOR"
        }
    ],
    "message": "SUCCESS"
}

POST /reports/{reportId}/shares

Shares a Report with the specified Users and Groups.

If called with a single Share object, and that user or group share already exists, error code 1025 will be returned. If called with an array of Share objects, and one or more user or group shares in the array already exist, they will be ignored and omitted from the response.

Access Scope SHARE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Parameters sendEmail (optional): Either true or false to indicate whether or not to notify the user by email. Default is false.
Request Body Share object or an array of Share objects, with the following attributes:
  • email (optional): the individual share recipient’s email address
  • groupId (optional): the group share recipient’s group ID
  • accessLevel (required)
  • subject (optional): The subject of the email that will optionally be sent to notify the recipient.
  • message (optional): The message to be included in the body of the email that will optionally be sent to the recipient.
  • ccMe (optional): Boolean flag to indicate whether or not to CC the user sharing the sheet.
NOTE: One of email or groupId must be specified, but not both.
Returns Result object containing either a single Share object or an array of Share objects, corresponding to what was specified in the request.

Update Report Share

Example Request:

curl https://api.smartsheet.com/2.0/reports/{reportId}/shares/{shareId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X PUT \
-d '{"accessLevel": "VIEWER"}'

Example Response:

{
    "resultCode": 0,
    "result": {
        "id": "AAAFeF82FOeE",
        "type": "USER",
        "userId": 1539725208119172,
        "email": "jane.doe@smartsheet.com",
        "name": "Jane Doe",
        "accessLevel": "VIEWER"
    },
    "message": "SUCCESS"
}

PUT /reports/{reportId}/shares/{shareId}

Updates the access level of a User or Group for the specified Report.

Access Scope SHARE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body Share object limited to the following attribute:
  • accessLevel (string)
Returns Result object containing the modified Share object

Sheet Sharing

Delete Sheet Share

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/shares/{shareId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE

Example Response:

{
    "message": "SUCCESS",
    "resultCode": 0
}

DELETE /sheets/{sheetId}/shares/{shareId}

Deletes the Share specified in the URL.

Access Scope SHARE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Returns Result object

Get Sheet Share

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/shares/{shareId} \
-H "Authorization: Bearer ACCESS_TOKEN" 

Example Response:

{
    "id": "AQAISF82FOeE",
    "type": "GROUP",
    "groupId": 2331373580117892,
    "name": "Group 1",
    "accessLevel": "ADMIN"
}

GET /sheets/{sheetId}/shares/{shareId}

Gets the Share specified in the URL.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Returns Share object

List Sheet Shares

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/shares \
-H "Authorization: Bearer ACCESS_TOKEN" 

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 2,
    "data": [
        {
            "id": "AAAQSF82FOeE",
            "type": "USER",
            "userId": 4583173393803140,
            "email": "john.doe@smartsheet.com",
            "name": "John Doe",
            "accessLevel": "OWNER"
        },
        {
            "id": "AQAISF82FOeE",
            "type": "GROUP",
            "groupId": 2331373580117892,
            "name": "Group 1",
            "accessLevel": "ADMIN"
        }
    ]
}

GET /sheets/{sheetId}/shares

Gets a list of all Users and Groups to whom the specified Sheet is shared, and their access level.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns IndexResult object containing an array of Share objects

Share Sheet

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/shares?sendEmail=true \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '[{"email": "jane.doe@smartsheet.com", "accessLevel": "EDITOR"}]'

Example Response:

{
    "resultCode": 0,
    "result": [
        {
            "id": "AAAFeF82FOeE",
            "type": "USER",
            "userId": 1539725208119172,
            "email": "jane.doe@smartsheet.com",
            "name": "Jane Doe",
            "accessLevel": "EDITOR"
        }
    ],
    "message": "SUCCESS"
}

POST /sheets/{sheetId}/shares

Shares a Sheet with the specified Users and Groups.

If called with a single Share object, and that user or group share already exists, error code 1025 will be returned. If called with an array of Share objects, and one or more user or group shares in the array already exist, they will be ignored and omitted from the response.

Access Scope SHARE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Parameters sendEmail (optional): Either true or false to indicate whether or not to notify the user by email. Default is false.
Request Body Share object or an array of Share objects, with the following attributes:
  • email (optional): the individual share recipient’s email address
  • groupId (optional): the group share recipient’s group ID
  • accessLevel (required)
  • subject (optional): The subject of the email that will optionally be sent to notify the recipient.
  • message (optional): The message to be included in the body of the email that will optionally be sent to the recipient.
  • ccMe (optional): Boolean flag to indicate whether or not to CC the user sharing the sheet.
NOTE: One of email or groupId must be specified, but not both.
Returns Result object containing either a single Share object or an array of Share objects, corresponding to what was specified in the request.

Update Sheet Share

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{reportId}/shares/{shareId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X PUT \
-d '{"accessLevel": "VIEWER"}'

Example Response:

{
    "resultCode": 0,
    "result": {
        "id": "AAAFeF82FOeE",
        "type": "USER",
        "userId": 1539725208119172,
        "email": "jane.doe@smartsheet.com",
        "name": "Jane Doe",
        "accessLevel": "VIEWER"
    },
    "message": "SUCCESS"
}

PUT /sheets/{sheetId}/shares/{shareId}

Updates the access level of a User or Group for the specified Sheet.

Access Scope SHARE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body Share object limited to the following attribute:
  • accessLevel (string)
Returns Result object containing the modified Share object

Workspace Sharing

Delete Workspace Share

Example Request:

curl https://api.smartsheet.com/2.0/workspaces/{workspaceId}/shares/{shareId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE

Example Response:

{
    "message": "SUCCESS",
    "resultCode": 0
}

DELETE /workspaces/{workspaceId}/shares/{shareId}

Deletes the Share specified in the URL.

Access Scope ADMIN_WORKSPACES
Headers Authorization: Bearer ACCESS_TOKEN
Returns Result object

Get Workspace Share

Example Request:

curl https://api.smartsheet.com/2.0/workspaces/{workspaceId}/shares/{shareId} \
-H "Authorization: Bearer ACCESS_TOKEN" 

Example Response:

{
    "id": "AQAISF82FOeE",
    "type": "GROUP",
    "groupId": 2331373580117892,
    "name": "Group 1",
    "accessLevel": "ADMIN"
}

GET /workspaces/{workspaceId}/shares/{shareId}

Gets the Share specified in the URL.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Returns Share object

List Workspace Shares

Example Request:

curl https://api.smartsheet.com/2.0/workspaces/{workspaceId}/shares \
-H "Authorization: Bearer ACCESS_TOKEN" 

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 2,
    "data": [
        {
            "id": "AAAQSF82FOeE",
            "type": "USER",
            "userId": 4583173393803140,
            "email": "john.doe@smartsheet.com",
            "name": "John Doe",
            "accessLevel": "OWNER"
        },
        {
            "id": "AQAISF82FOeE",
            "type": "GROUP",
            "groupId": 2331373580117892,
            "name": "Group 1",
            "accessLevel": "ADMIN"
        }
    ]
}

GET /workspaces/{workspaceId}/shares

Gets a list of all Users and Groups to whom the specified Workspace is shared, and their access level.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns IndexResult object containing an array of Share objects

Share Workspace

Example Request:

curl https://api.smartsheet.com/2.0/workspaces/{workspaceId}/shares?sendEmail=true \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '[{"email": "jane.doe@smartsheet.com", "accessLevel": "EDITOR"}]'

Example Response:

{
    "resultCode": 0,
    "result": [
        {
            "id": "AAAFeF82FOeE",
            "type": "USER",
            "userId": 1539725208119172,
            "email": "jane.doe@smartsheet.com",
            "name": "Jane Doe",
            "accessLevel": "EDITOR"
        }
    ],
    "message": "SUCCESS"
}

POST /workspaces/{workspaceId}/shares

Shares a Workspace with the specified Users and Groups.

If called with a single Share object, and that user or group share already exists, error code 1025 will be returned. If called with an array of Share objects, and one or more user or group shares in the array already exist, they will be ignored and omitted from the response.

Access Scope ADMIN_WORKSPACES
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Parameters sendEmail (optional): Either true or false to indicate whether or not to notify the user by email. Default is false.
Request Body Share object or an array of Share objects, with the following attributes:
  • email (optional): the individual share recipient’s email address
  • groupId (optional): the group share recipient’s group ID
  • accessLevel (required)
  • subject (optional): The subject of the email that will optionally be sent to notify the recipient.
  • message (optional): The message to be included in the body of the email that will optionally be sent to the recipient.
  • ccMe (optional): Boolean flag to indicate whether or not to CC the user sharing the sheet.
NOTE: One of email or groupId must be specified, but not both.
Returns Result object containing either a single Share object or an array of Share objects, corresponding to what was specified in the request.

Update Workspace Share

Example Request:

curl https://api.smartsheet.com/2.0/workspaces/{workspaceId}/shares/{shareId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X PUT \
-d '{"accessLevel": "VIEWER"}'

Example Response:

{
    "resultCode": 0,
    "result": {
        "id": "AAAFeF82FOeE",
        "type": "USER",
        "userId": 1539725208119172,
        "email": "jane.doe@smartsheet.com",
        "name": "Jane Doe",
        "accessLevel": "VIEWER"
    },
    "message": "SUCCESS"
}

PUT /workspaces/{workspaceId}/shares/{shareId}

Updates the access level of a User or Group for the specified Workspace.

Access Scope ADMIN_WORKSPACES
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body Share object limited to the following attribute:
  • accessLevel (string)
Returns Result object containing the modified Share object

Sheets

A Sheet can exist in a user’s Sheets folder (Home), in a Folder, or in a Workspace. It is comprised of Columns, Rows, and Cells, and may optionally contain Attachments and/or Discussions.

Objects

Sheet Object

id number Sheet ID
name string Sheet name
version number A number that is incremented every time a Sheet is modified
totalRowCount number The total number of rows in the Sheet
accessLevel string User’s permissions on the Sheet
effectiveAttachmentOptions array Array of enum strings (see Attachment.attachmentType) indicating the allowable attachment options for the current User and Sheet
readOnly boolean Returned only if the Sheet belongs to an expired trial (value = “true”)
ganttEnabled boolean Flag to indicate that Gantt is enabled
dependenciesEnabled boolean Flag to indicate that dependencies are enabled
resourceManagementEnabled boolean Flag to indicate that resource management is enabled
favorite boolean Returned only if the User has marked this sheet as a favorite in their Home tab (value = “true”)
showParentRowsForFilters boolean Returned only if there are column filters on the Sheet. Value = “true” if “show parent rows” is enabled for the filters.
userSettings SheetUserSettings A SheetUserSettings object containing the current user’s sheet-specific settings.
permalink string Direct URL to the Sheet
source Source A Source object indicating the Sheet or Template from which this sheet was created
createdAt timestamp Time that the Sheet was created
modifiedAt timestamp Time that the Sheet was modified
columns Column[] Array of Column objects
rows Row[] Array of Row objects
discussions Discussion[] Array of Discussion objects
Only returned if the include query string parameter contains discussions.
attachments Attachment[] Array of Attachment objects
Only returned if the include query string parameter contains attachments.
fromId number The ID of the Template from which to create the Sheet. This attribute can be specified in a request, but will never be present in a response.

SheetPublish Object

readOnlyLiteEnabled boolean Status of Read-Only HTML
readOnlyFullEnabled boolean Status of Read-Only Full
readWriteEnabled boolean Status of Edit by Anyone
icalEnabled boolean Status of iCal
readOnlyLiteUrl string URL for Read-Only HTML
readOnlyFullUrl string URL for Read-Only Full
readWriteUrl string URL for Edit by Anyone
icalUrl string URL for iCal

SheetUserSettings Object

Represents individual user settings for a specific sheet. User settings may be updated even on sheets where the current user only has read access (e.g. viewer permissions or a read-only sheet).

criticalPathEnabled boolean Does this user have “Show Critical Path” turned on for this sheet? Note this setting only has an effect on project sheets with dependencies enabled.

Source Object

id number ID of the Sheet or Template from which the enclosing sheet was created
type string “sheet” or “template”

Create Sheet

To create a Sheet from scratch, use one of the following operations (according to where you want to create the Sheet):

To create a Sheet from a Template, see Create Sheet from Template.

Create Sheet in “Sheets” folder

Example Request:

curl https://api.smartsheet.com/2.0/sheets \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name":"newsheet","columns":[{"title":"Favorite","type":"CHECKBOX","symbol":"STAR"}, {"title":"Primary Column", "primary":true,"type":"TEXT_NUMBER"}, {"title":"Status", "type":"PICKLIST", "options":["Not Started","Started","Completed"]}]}'

Example Response:

{
    "message": "SUCCESS",
    "result": {
        "accessLevel": "OWNER",
        "columns": [
            {
                "id": 7960873114331012,
                "index": 0,
                "symbol": "STAR",
                "title": "Favorite",
                "type": "CHECKBOX"
            },
            {
                "id": 642523719853956,
                "index": 1,
                "primary": true,
                "title": "Primary Column",
                "type": "TEXT_NUMBER"
            },
            {
                "id": 5146123347224452,
                "index": 2,
                "options": [
                    "Not Started",
                    "Started",
                    "Completed"
                ],
                "title": "Status",
                "type": "PICKLIST"
            }
        ],
        "id": 2331373580117892,
        "name": "newsheet",
        "permalink": "https://app.smartsheet.com/b/home?lx=0HHzeGnfHik-N13ZT8pU7g"
    },
    "resultCode": 0
}

POST /sheets

Creates a Sheet from scratch in the user’s Sheets folder (Home). To create a Sheet from scratch in a subfolder of the Sheets folder, use Create Sheet in Folder.

Access Scope CREATE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body Sheet object, limited to the following attributes:
  • name (required) - need not be unique
  • columns (required) - array of Column objects, limited to the following attributes:
    • title (required), must be unique within the Sheet
    • primary (required)
    • type (required)
    • symbol (optional)
    • options (optional)
    • systemColumnType (optional)
    • autoNumberFormat (optional)
    • width (optional)
Returns Result object containing a Sheet object for newly created Sheet, limited to the following attributes:
  • id
  • name
  • accessLevel
  • permalink
  • columns

Create Sheet in Folder

Example Request:

curl https://api.smartsheet.com/2.0/folders/{folderId}/sheets \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name":"newsheet","columns":[{"title":"Favorite","type":"CHECKBOX","symbol":"STAR"}, {"title":"Primary Column", "primary":true,"type":"TEXT_NUMBER"}, {"title":"Status", "type":"PICKLIST", "options":["Not Started","Started","Completed"]}]}'

Example Response:

{
    "message": "SUCCESS",
    "result": {
        "accessLevel": "OWNER",
        "columns": [
            {
                "id": 7960873114331012,
                "index": 0,
                "symbol": "STAR",
                "title": "Favorite",
                "type": "CHECKBOX"
            },
            {
                "id": 642523719853956,
                "index": 1,
                "primary": true,
                "title": "Primary Column",
                "type": "TEXT_NUMBER"
            },
            {
                "id": 5146123347224452,
                "index": 2,
                "options": [
                    "Not Started",
                    "Started",
                    "Completed"
                ],
                "title": "Status",
                "type": "PICKLIST"
            }
        ],
        "id": 2331373580117892,
        "name": "newsheet",
        "permalink": "https://app.smartsheet.com/b/home?lx=0HHzeGnfHik-N13ZT8pU7g"
    },
    "resultCode": 0
}

POST /folders/{folderId}/sheets

Creates a Sheet from scratch in the specified Folder.

Access Scope CREATE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body Sheet object, limited to the following attributes:
  • name (required) - need not be unique
  • columns (required) - array of Column objects, limited to the following attributes:
    • title (required), must be unique within the Sheet
    • primary (required)
    • type (required)
    • symbol (optional)
    • options (optional)
    • systemColumnType (optional)
    • autoNumberFormat (optional)
    • width (optional)
Returns Result object containing a Sheet object for newly created Sheet, limited to the following attributes:
  • id
  • name
  • accessLevel
  • permalink
  • columns

Create Sheet in Workspace

Example Request:

curl https://api.smartsheet.com/2.0/workspaces/{workspaceId}/sheets \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name":"newsheet","columns":[{"title":"Favorite","type":"CHECKBOX","symbol":"STAR"}, {"title":"Primary Column", "primary":true,"type":"TEXT_NUMBER"}, {"title":"Status", "type":"PICKLIST", "options":["Not Started","Started","Completed"]}]}'

Example Response:

{
    "message": "SUCCESS",
    "result": {
        "accessLevel": "OWNER",
        "columns": [
            {
                "id": 7960873114331012,
                "index": 0,
                "symbol": "STAR",
                "title": "Favorite",
                "type": "CHECKBOX"
            },
            {
                "id": 642523719853956,
                "index": 1,
                "primary": true,
                "title": "Primary Column",
                "type": "TEXT_NUMBER"
            },
            {
                "id": 5146123347224452,
                "index": 2,
                "options": [
                    "Not Started",
                    "Started",
                    "Completed"
                ],
                "title": "Status",
                "type": "PICKLIST"
            }
        ],
        "id": 2331373580117892,
        "name": "newsheet",
        "permalink": "https://app.smartsheet.com/b/home?lx=0HHzeGnfHik-N13ZT8pU7g"
    },
    "resultCode": 0
}

POST /workspaces/{workspaceId}/sheets

Creates a Sheet from scratch at the top-level of the specified Workspace. To create a Sheet from scratch in a Folder within a Workspace, use Create Sheet in Folder.

Access Scope CREATE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body Sheet object, limited to the following attributes:
  • name (required) - need not be unique
  • columns (required) - array of Column objects, limited to the following attributes:
    • title (required), must be unique within the Sheet
    • primary (required)
    • type (required)
    • symbol (optional)
    • options (optional)
    • systemColumnType (optional)
    • autoNumberFormat (optional)
    • width (optional)
Returns Result object containing a Sheet object for newly created Sheet, limited to the following attributes:
  • id
  • name
  • accessLevel
  • permalink
  • columns

Create Sheet from Template

To create a Sheet from a Template, use one of the following operations (according to where you want to create the Sheet):

To create a Sheet from scratch, see Create Sheet.

Create Sheet in “Sheets” folder from Template

Example Request:

curl https://api.smartsheet.com/2.0/sheets?include=data,attachments,discussions \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name":"newsheet", "fromId": 7679398137620356}'

Example Response:

{
    "message": "SUCCESS",
    "result": {
        "accessLevel": "OWNER",
        "id": 7960873114331012,
        "name": "newsheet",
        "permalink": "https://app.smartsheet.com/b/home?lx=lbKEF1UakfTNJTZ5XkpxWg"
    },
    "resultCode": 0
}

POST /sheets

Creates a Sheet in the user’s Sheets folder (Home), from the specified Template. To create a Sheet in a subfolder of the Sheets folder, use Create Sheet in Folder from Template.

Access Scope CREATE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Parameters include (optional) – comma-separated list of elements to copy from the Template or Sheet:
  • data
  • attachments
  • discussions
  • cellLinks
  • forms
Request Body Sheet object, limited to the following attributes:
  • name (required) - need not be unique
  • fromId (required) - the ID of the Template from which to create the Sheet
Returns Result object containing a Sheet object for the newly created Sheet, limited to the following attributes:
  • id
  • name
  • accessLevel
  • permalink

Create Sheet in Folder from Template

Example Request:

curl https://api.smartsheet.com/2.0/folders/{folderId}/sheets?include=data,attachments,discussions \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name":"newsheet", "fromId": 7679398137620356}'

Example Response:

{
    "message": "SUCCESS",
    "result": {
        "accessLevel": "OWNER",
        "id": 7960873114331012,
        "name": "newsheet",
        "permalink": "https://app.smartsheet.com/b/home?lx=lbKEF1UakfTNJTZ5XkpxWg"
    },
    "resultCode": 0
}

POST /folders/{folderId}/sheets

Creates a Sheet in the specified Folder, from the specified Template.

Access Scope CREATE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Parameters include (optional) – comma-separated list of elements to copy from the Template or Sheet:
  • data
  • attachments
  • discussions
  • cellLinks
  • forms
Request Body Sheet object, limited to the following attributes:
  • name (required) - need not be unique
  • fromId (required) - the ID of the Template from which to create the Sheet
Returns Result object containing a Sheet object for the newly created Sheet, limited to the following attributes:
  • id
  • name
  • accessLevel
  • permalink

Create Sheet in Workspace from Template

Example Request:

curl https://api.smartsheet.com/2.0/workspaces/{workspaceId}/sheets?include=data,attachments,discussions \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name":"newsheet", "fromId": 7679398137620356}'

Example Response:

{
    "message": "SUCCESS",
    "result": {
        "accessLevel": "OWNER",
        "id": 7960873114331012,
        "name": "newsheet",
        "permalink": "https://app.smartsheet.com/b/home?lx=lbKEF1UakfTNJTZ5XkpxWg"
    },
    "resultCode": 0
}

POST /workspaces/{workspaceId}/sheets

Creates a Sheet at the top-level of the specified Workspace, from the specified Template. To create a Sheet in a Folder within a Workspace, use Create Sheet in Folder from Template.

Access Scope CREATE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Parameters include (optional) – comma-separated list of elements to copy from the Template or Sheet:
  • data
  • attachments
  • discussions
  • cellLinks
  • forms
Request Body Sheet object, limited to the following attributes:
  • name (required) - need not be unique
  • fromId (required) - the ID of the Template from which to create the Sheet
Returns Result object containing a Sheet object for the newly created Sheet, limited to the following attributes:
  • id
  • name
  • accessLevel
  • permalink

Delete Sheet

Example Request:

...curl https://api.smartsheet.com/2.0/sheets/{sheetId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE

Example Response:

{
    "resultCode": 0,
    "message": "SUCCESS"
}

DELETE /sheets/{sheetId}

Deletes the Sheet specified in the URL.

Access Scope DELETE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Returns Result object

Get Sheet Version

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/version \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
    "version": "23"
}

GET /sheets/{sheetId}/version

Gets the Sheet version without loading the entire Sheet.

The following actions increment Sheet version:

  • add/modify cell value
  • add/modify row
  • add/modify Discussion/Comment
  • change formatting
  • add/remove/update version attachment
  • cell updated via cell link

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Returns A simple object with only a version attribute

Get Sheet

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId} \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
    "accessLevel": "OWNER",
    "columns": [
        {
            "id": 4583173393803140,
            "index": 0,
            "primary": true,
            "title": "Primary Column",
            "type": "TEXT_NUMBER"
        },
        {
            "id": 2331373580117892,
            "index": 1,
            "options": [
                "new",
                "in progress",
                "completed"
            ],
            "title": "status",
            "type": "PICKLIST"
        }
    ],
    "createdAt": "2012-07-24T18:22:29-07:00",
    "id": 4583173393803140,
    "modifiedAt": "2012-07-24T18:30:52-07:00",
    "name": "sheet 1",
    "permalink": "https://app.smartsheet.com/b/home?lx=pWNSDH9itjBXxBzFmyf-5w",
    "rows": []
}

GET /sheets/{sheetId}

Gets the Sheet specified in the URL. Returns the Sheet, including Rows, and optionally populated with Discussion and Attachment objects.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters include (optional) – a comma-separated list of optional objects to include in the response.
Supports all Row Include Flags with the following differences:
  • discussions: includes sheet-level and row-level discussions
  • attachments: includes sheet-level and row-level attachments
  • format: includes column, row, and cell formatting
  • filters: includes column filters, and row.filteredOut attribute
Also supports the source include flag, which adds the source object indicating which sheet or template the sheet was created from, if any.
exclude (optional): when specified with a value of “nonexistentCells”, response will not include cells that have never contained any data
rowIds (optional): a comma-separated list of Row IDs on which to filter the rows included in the result
rowNumbers (optional): a comma-separated list of Row numbers on which to filter the rows included in the result. Non-existent row numbers are ignored.
columnIds (optional): a comma-separated list of Column IDs. The response will contain only the specified columns in the “columns” array, and individual rows’ “cells” array will only contain cells in the specified columns.
pageSize (optional): number of rows per page to include with the sheet. If neither pageSize or page are specified, returns all rows in the sheet. If only page is specified, defaults to a page size of 100.
page (optional): which page number (1-based) to return. If not specified, the default value is 1. If a page number is specified that is greater than the number of total pages, the last page will be returned.
Returns Sheet object, populated according to the include parameter

Get Sheet as Excel / PDF / CSV

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}?paperSize=A1 \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Accept: application/pdf" 
-o  output.pdf

Example Response:

See local file named "output.pdf"

GET /sheets/{sheetId}

Gets the Sheet in the format specified, based on the Sheet ID.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Accept – must be set to one of the following values:
  • application/pdf
  • application/vnd.ms-excel
  • text/csv
Parameters paperSize (optional) – applies to PDF only, must be one of:
  • LETTER (default)
  • LEGAL
  • WIDE (same as 11x17)
  • ARCHD
  • A4
  • A3
  • A2
  • A1
  • A0
Returns The file in either Excel, PDF, or CSV format.

List All Org Sheets

Example Request:

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

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 1,
    "data": [
        {
            "id": 2894323533539204,
            "name": "New Sheet",
            "owner": "john.doe@smartsheet.com",
            "ownerId": 995857572373
        }
    ]
}

GET /users/sheets

Gets the list of all Sheets owned by the members of the account (organization).

This operation supports pagination of results.

Access Scope ADMIN_USERS
Headers Authorization: Bearer ACCESS_TOKEN
Returns IndexResult object containing an array of Sheet objects, limited to the following attributes:
  • id
  • name
  • owner (email address)
  • ownerId

List Sheets

Example Request:

curl https://api.smartsheet.com/2.0/sheets \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 2,
    "data": [
        {
            "accessLevel": "OWNER",
            "id": 4583173393803140,
            "name": "sheet 1",
            "permalink": "https://app.smartsheet.com/b/home?lx=xUefSOIYmn07iJJesvSHCQ"
        },
        {
            "accessLevel": "OWNER",
            "id": 2331373580117892,
            "name": "sheet 2",
            "permalink": "https://app.smartsheet.com/b/home?lx=xUefSOIYmn07iJJrthEFTG"
        }
    ]
}

GET /sheets

Gets the list of all Sheets that the User has access to, in alphabetical order, by name.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters include (optional): when specified with a value of “source”, response will include the source for any sheet that was created from another sheet or template

This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns IndexResult object containing an array of Sheet objects limited to the following attributes:
  • id
  • name
  • accessLevel
  • permalink
  • source (if include parameter specified)

Publish Sheet

Get Sheet Publish Status

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/publish \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
    "readOnlyLiteEnabled": true,
    "readOnlyFullEnabled": false,
    "readWriteEnabled": false,
    "icalEnabled": false,
    "readOnlyLiteUrl": "https://publish.smartsheet.com/6d35fa6c99334d4892f9591cf6065"
}

GET /sheets/{sheetId}/publish

Gets the status of the Publish settings of the Sheet, including the URLs of any enabled publishings.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Returns SheetPublish object

Set Sheet Publish Status

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/publish \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X PUT \
-d '{"readOnlyLiteEnabled": true,"readOnlyFullEnabled": false,"readWriteEnabled": false,"icalEnabled": false}'

Example Response:

{
    "message": "SUCCESS",
    "result": {
        "icalEnabled": false,
        "readOnlyFullEnabled": false,
        "readOnlyLiteEnabled": true,
        "readOnlyLiteUrl": "http://publish.smartsheet.com/9862638d9c444014b5d7a114d436e99d",
        "readWriteEnabled": false
    },
    "resultCode": 0
}

PUT /sheets/{sheetId}/publish

Sets the publish status of the Sheet and returns the new status, including the URLs of any enabled publishings.

Access Scope ADMIN_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body SheetPublish object limited to the following attributes:
  • readOnlyLiteEnabled
  • readOnlyFullEnabled
  • readWriteEnabled
  • icalEnabled
Returns Result object containing a SheetPublish object

Search Sheet

Example Request:

curl https://api.smartsheet.com/2.0/search/sheets/{sheetId}?query=stuff \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
    "results": [
        {
            "contextData": [
                "Discussion 1"
            ],
            "objectId": 1888207043356548,
            "objectType": "discussion",
            "parentObjectId": 7141187195824004,
            "parentObjectName": "Sheet 1",
            "parentObjectType": "sheet",
            "text": "discussion stuff goes here"
        }
    ],
    "totalCount": 1
}

GET /search/sheets/{sheetId}

Searches a Sheet for the specified text.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters query (required): Text with which to perform the search.
Returns SearchResult object that contains a maximum of 100 SearchResultems

Send Sheet via Email

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/emails \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{"sendTo" : [{"email": "john.doe@smartsheet.com"}, {"groupId": 2258118617917316}], "subject": "Check these rows out!", "message": "Here are the rows I mentioned in our meeting", "ccMe": false, "format": "PDF", formatDetails": {"paperSize": "A4"}}'

Example Response:

{
    "message": "SUCCESS",
    "resultCode": 0
}

POST /sheets/{sheetId}/emails

Sends the Sheet as a PDF attachment via email to the designated recipients.

Access Scope SHARE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body SheetEmail object
Returns Result object

Share Sheet

For details about Sheet sharing, see Sheet Sharing.

Update Sheet

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X PUT \
-d '{"name":"New Sheet Name", "userSettings": {"criticalPathEnabled": true}}'

Example Response:

{
    "message": "SUCCESS",
    "result": {
        "id": 7960873114331012,
        "name": "New Sheet Name",
        "accessLevel": "OWNER",
        "userSettings": {
            "criticalPathEnabled": true
        },
        "permalink": "https://app.smartsheet.com/b/home?lx=RE8LkzA48kPRWTzcgEYOga"
    },
    "resultCode": 0
}

PUT /sheets/{sheetId}

Updates the Sheet specified in the URL.

To modify Sheet contents, see Add Row(s), Update Row(s), and Update Column.

This operation can be used to update an individual user’s sheet settings. If the request body contains only the userSettings attribute, this operation may be performed even if the user only has read-only access to the sheet (i.e. the user has viewer permissions, or the sheet is read-only).

Access Scope ADMIN_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body Sheet object limited to the following attributes:
Returns Result object containing a Sheet object for the newly created Sheet

A Sheet is comprised of Columns, Rows, and Cells, and may optionally contain Attachments and/or Discussions.

Sheet Attachments

For details about working with a Sheet’s attachments, see Attachments.

Sheet Cells

For details about working with a Sheet’s cells, see Cells.

Sheet Columns

For details about working with a Sheet’s columns, see Columns.

Sheet Discussions

There are two ways to get discussion-related information for a Sheet:

Operation Returns
Get Sheet
(with include parameter value “discussions”)
Response does not contain the Comments that comprise each Discussion.
Get All Discussions
(with include parameter value “comments”)
Response does contain the Comments that comprise each Discussion.

For more information about working with a Sheet’s discussions, see Discussions.

Sheet Rows

For details about working with a Sheet’s rows, see Rows.

Templates

A Template can be used to create a Sheet, as described in Create Sheet from Template.

Objects

Template Object

id number Template ID
name string Template name
description string Template description
accessLevel string User’s permissions on the Template

List Public Templates

Example Request:

curl https://api.smartsheet.com/2.0/templates/public \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 2,
    "data": [
        {
            "id": 3457273486960516,
            "name": "template 1",
            "accessLevel": "OWNER",
            "description": "This is template 1"
        },
        {
            "id": 34572734869609346,
            "name": "template 2",
            "accessLevel": "VIEWER",
            "description": "This is template 2"
        }
    ]
}

GET /templates/public

Gets the list of public Templates to which the user has access.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns IndexResult object containing an array of Template objects

List User-created Templates

Example Request:

curl https://api.smartsheet.com/2.0/templates \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 2,
    "data": [
        {
            "id": 3457273486960516,
            "name": "template 1",
            "accessLevel": "OWNER",
            "description": "This is template 1"
        },
        {
            "id": 34572734869609346,
            "name": "template 2",
            "accessLevel": "VIEWER",
            "description": "This is template 2"
        }
    ]
}

GET /templates

Gets the list of user-created Templates to which the user has access.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns IndexResult object containing an array of Template objects

Token

The Smartsheet API utilizes OAuth 2.0 for Authentication and Authorization. An Authorization HTTP header containing an Access Token is required to authenticate requests. For more information, see Authentication.

Get Access Token

Example Request:

curl https://api.smartsheet.com/2.0/token \
-d 'grant_type=authorization_code&code={your_code}&client_id={your_client_id}&redirect_uri={redirect_uri}&hash={SHA_256(client_secret|code)}' \
-X POST

Example Response:

{
   "access_token": "Access Token Value",
   "token_type": "bearer",
   "refresh_token": "Refresh Token Value",
   "expires_in": "#_of_seconds_before_token_expires"
}

POST /token

Gets an access token, as part of the oAuth process. For more information, see oAuth Flow.

Parameters grant_type (required) – must be set to “authorization_code”
client_id (required) – client id for your app
code (required) – authorization code returned in the previous step
redirect_uri (required) – redirect URL registered for your app, including the protocol (e.g., “http://”); if not provided, the redirect URL set during registration is used.
hash (required) – SHA-256 hash of your client secret concatenated with a pipe and the authorization code. The client_secret is never sent with the request.

Refresh Access Token

Example Request:

curl https://api.smartsheet.com/2.0/token \
-d 'grant_type=refresh_token&refresh_token={your_refresh_token}
&client_id={your_client_id}&redirect_uri={redirect_uri}
&hash={SHA_256(client_secret|refresh_token)}' \
-X POST

Example Response:

{
   "access_token": "Newly refreshed Access Token",
   "expires_in": "#_of_seconds_before_token_expires",
   "token_type": "bearer",
   "refresh_token": "New refresh token"
}

POST /token

Refreshes an access token, as part of the oAuth process. For more information, see oAuth Flow.

Parameters grant_type (required) – must be set to “refresh_token”
client_id (required) – client id for your app
refresh_token (required) – refresh_token value that came with the access token
redirect_uri (required) – redirect URL registered for your app, including the protocol (e.g., “http://”)
hash (required) – SHA-256 hash of your client secret concatenated with a pipe and the refresh token value

Revoke Access Token

Example Request:

curl https://api.smartsheet.com/2.0/token \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE

Example Response:

{
    "message": "SUCCESS",
    "resultCode": 0
}

DELETE /token

Revokes the access token used to make this request. The access token will no longer be valid, and subsequent API calls made using the token will fail.

Headers Authorization: Bearer ACCESS_TOKEN
Returns Result object

Users

Objects

User Object

id number User ID
email string User’s email address
name string User’s full name (read-only)
firstName string User’s first name
lastName string User’s last name
admin boolean Flag indicating whether the user is a system admin (can manage users and account)
licensedSheetCreator boolean Flag indicating whether the user is a licensed user (can create and own sheets)
groupAdmin boolean Flag indicating whether the user is a group admin (can create and edit groups)
resourceViewer boolean Flag indicating whether the user is a resource viewer (can access resource views)
status string User status, set to one of the following values:
  • ACTIVE
  • PENDING
  • DECLINED

UserProfile Object

id number Current user’s ID
email string Current user’s email address
firstName string Current user’s first name
lastName string Current user’s last name
timeZone string Current user’s time zone ID
locale string Current user’s locale (see Server Information)
account Account Account object representing the current user’s customer account

Account Object

name string Account name
id number Account ID

Add User

Example Request:

curl https://api.smartsheet.com/2.0/users?sendEmail=true \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{"firstName": "John", "lastName": "Doe", "email": "NEW_USER_EMAIL", "admin": false, "licensedSheetCreator": true}'

Example Response:

{
    "message": "SUCCESS",
    "result": {
        "admin": false,
        "email": "NEW_USER_EMAIL",
        "name": "John Doe",
        "id": 1768423626696580,
        "licensedSheetCreator": true
    },
    "resultCode": 0
}

POST /users

Adds a User to the organization.

Access Scope ADMIN_USERS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Parameters sendEmail (optional): A boolean flag indicating whether or not to send a welcome email. Defaults to false.
Request Body User object with the following attributes:
  • email (required)
  • admin (required)
  • licensedSheetCreator (required)
  • firstName (optional)
  • lastName (optional)
  • resourceViewer (optional)
Returns Result object containing the newly created User object.

Get Current User

Example Request:

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

Example Response:

{
    "email": "john.doe@smartsheet.com",
    "firstName": "John",
    "lastName": "Doe",
    "id": 48569348493401200
}

GET /users/me

Gets the current User.

Access Scope all scopes
Headers Authorization: Bearer ACCESS_TOKEN
Returns UserProfile object

Get User

Example Request:

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

Example Response:

{
    "email": "john.doe@smartsheet.com",
    "firstName": "John",
    "lastName": "Doe",
    "id": 48569348493401200
}

GET /users/{userId}

Gets the User specified in the URL.

Access Scope READ_USERS
Headers Authorization: Bearer ACCESS_TOKEN
Returns UserProfile object

List All Org Sheets

Example Request:

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

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 1,
    "data": [
        {
            "id": 2894323533539204,
            "name": "New Sheet",
            "owner": "john.doe@smartsheet.com",
            "ownerId": 995857572373
        }
    ]
}

GET /users/sheets

Gets the list of all Sheets owned by the members of the account (organization).

This operation supports pagination of results.

Access Scope ADMIN_USERS
Headers Authorization: Bearer ACCESS_TOKEN
Returns IndexResult object containing an array of Sheet objects, limited to the following attributes:
  • id
  • name
  • owner (email address)
  • ownerId

List Users

Example Request:

curl https://api.smartsheet.com/2.0/users?email=john.doe@smartsheet.com \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 1,
    "data": [
        {
            "id": 94094820842,
            "admin": true,
            "email": "john.doe@smartsheet.com",
            "name": "John Doe",
            "licensedSheetCreator": true,
            "status": "ACTIVE"
        }
    ]
}

GET /users

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

Access Scope READ_USERS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters email (optional): Comma-separated list of email addresses on which to filter the results

This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns IndexResult object containing an array of User objects

Remove User

Example Request:

curl https://api.smartsheet.com/2.0/users/{userId}?transferTo=USER_ID&removeFromSharing=true \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE

Example Response:

{
    "message": "SUCCESS",
    "resultCode": 0
}

DELETE /users/{userId}

Removes a User from an organization. User is transitioned to a free collaborator with read-only access to owned sheets (unless those are optionally transferred to another user).

Access Scope ADMIN_USERS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters transferTo (required if user owns groups): The ID of the user to transfer ownership to. If the user being deleted owns groups, they will be transferred to this user. If the user owns sheets, and transferSheets is true, then the deleted user’s sheets will be transferred to this user.
transferSheets (optional): If true, and transferTo is specified, the deleted user’s sheets will be transferred. Else, sheets will not be transferred. Defaults to false.
removeFromSharing (optional): Set to true to remove the user from sharing for all sheets/workspaces in the organization. If not specified, User will not be removed from sharing.
Returns Result object

Update User

Example Request:

curl https://api.smartsheet.com/2.0/users/{userId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X PUT \
-d '{"admin": false, "licensedSheetCreator": true}'

Example Response:

{
    "message": "SUCCESS",
    "result": {
        "admin": true,
        "licensedSheetCreator": true
    },
    "resultCode": 0
}

PUT /users/{userId}

Updates the User specified in the URL.

Access Scope ADMIN_USERS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body User object containing at least one of the following attributes:
  • admin (required)
  • licensedSheetCreator (required)
  • firstName (optional)
  • lastName (optional)
  • resourceViewer (optional)
Returns Result object containing the User object for the updated User

Workspaces

Objects

Workspace Object

id number Workspace ID
name string Workspace name
favorite boolean Returned only if the user has marked the Workspace as a Favorite in their Home tab (value = “true”)
accessLevel string User’s permissions on the Workspace
permalink string Direct URL to the Workspace
sheets Sheet[] Array of Sheet objects
folders Folder[] Array of Folder objects
reports Report[] Array of Report objects
templates Template[] Array of Template objects

Create Workspace

Example Request:

curl https://api.smartsheet.com/2.0/workspaces \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name": "New workspace"}'

Example Response:

{
    "message": "SUCCESS",
    "result": {
        "accessLevel": "OWNER",
        "id": 7960873114331012,
        "name": "New workspace",
        "permalink": "https://app.smartsheet.com/b/home?lx=rBU8QqUVPCJ3geRgl7L8yQ"
    },
    "resultCode": 0
}

POST /workspaces

Creates a Workspace.

Access Scope ADMIN_WORKSPACES
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body Workspace object, limited to the following attribute:
  • name (string) - required
Returns Result object containing a Workspace object for the newly created Workspace

Delete Workspace

Example Request:

curl https://api.smartsheet.com/2.0/workspaces/7960873114331012 \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE

Example Response:

{
    "message": "SUCCESS",
    "resultCode": 0
}

DELETE /workspaces/{id}

Deletes the specified Workspace (and its contents).

Access Scope ADMIN_WORKSPACES
Headers Authorization: Bearer ACCESS_TOKEN
Returns Result object

Get Workspace

Example Request:

curl https://api.smartsheet.com/2.0/workspaces/{workspaceid} \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
    "sheets": [
       {
            "id": 4583173393803140,
            "name": "sheet 1",
            "accessLevel": "OWNER",
            "permalink": "https://app.smartsheet.com/b/home?lx=8Z0XuFUEAkxmHCSsMw4Zg1"
       }
    ],
    "accessLevel": "OWNER",
    "id": 7116448184199044,
    "name": "New workspace",
    "permalink": "https://app.smartsheet.com/b/home?lx=8Z0XuFUEAkxmHCSsMw4Zgg"
}

GET /workspaces/{workspaceid}

Gets the specified Workspace (and lists its contents).

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters loadAll (optional) – true or false (defaults to false)
include (optional): when specified with a value of “source”, response will include the source for any sheet that was created from another sheet or template
Returns Workspace object

List Workspaces

Example Request:

curl https://api.smartsheet.com/2.0/workspaces \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 2,
    "data": [
        {
            "accessLevel": "OWNER",
            "id": 3457273486960516,
            "name": "workspace 1",
            "permalink": "https://app.smartsheet.com/b/home?lx=JNL0bgXtXc0pzni9tzAc4g"
        },
        {
            "accessLevel": "OWNER",
            "id": 7960873114331012,
            "name": "workspace 2",
            "permalink": "https://app.smartsheet.com/b/home?lx=JLiJbgXtXc0pzni9tzAKiR"
        }
    ]
}

GET /workspaces

Gets the list of Workspaces to which the user has access.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns IndexResult object containing an array of Workspace objects

Share Workspace

For details about Workspace sharing, see Workspace Sharing.

Update Workspace

Example Request:

curl https://api.smartsheet.com/2.0/workspaces/7960873114331012 \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X PUT \
-d '{"name": "Updated workspace"}'

Example Response:

{
    "message": "SUCCESS",
    "result": {
        "accessLevel": "OWNER",
        "id": 7960873114331012,
        "name": "Updated workspace",
        "permalink": "https://app.smartsheet.com/b/home?lx=rBU8QqUVPCJ3geRgl7L8yQ"
    },
    "resultCode": 0
}

PUT /workspaces/{id}

Updates the Workspace specified in the URL.

Access Scope ADMIN_WORKSPACES
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body Workspace object limited to the following attribute:
  • name (string)
Returns Result object containing the updated Workspace object

Workspace Folders

For details about working with folders in a Workspace, see Folders.

Workspace Sheets

For details about working with sheets in a Workspace, see Sheets.

Additional Reference

Other Objects

AutoNumberFormat Object

Object that describes how the the System Column type of “AUTO_NUMBER” is auto-generated.

prefix string The prefix. Can include the date tokens:
  • {YY}
  • {YYYY}
  • {MM}
  • {DD}
suffix string The suffix. Can include the date tokens:
  • {YY}
  • {YYYY}
  • {MM}
  • {DD}
fill string Indicates zero-padding. Must be between 0 and 10 “0” (zero) characters.
startingNumber number The starting number for the auto-id

IndexResult Object

Object returned for all GET operations against index endpoints. This object provides metadata which can be used to perform paging on potentially large data sets. See the Paging section for more information.

pageNumber number The current page in the full result set that the data array represents.
pageSize number The number of items in a page. Omitted if there is no limit to page size (and hence, all results are included). Unless otherwise specified, this defaults to 100 for most endpoints.
totalPages number The total number of pages in the full result set.
totalCount number The total number of items in the full result set.
data array An array of objects representing the current page of data in the result set.

Result Object

Object returned for all PUT operations and POST operations (and for some other operations).

resultCode number 0 (zero) if successful
message string Message that indicates the outcome of the request
result Object Object that was created or updated (if applicable)
version number New version of the Sheet (only available on select operations)

Formatting

Formatting data can optionally be included for columns, rows, and cells by adding the “include=format” query string parameter to any API operation that returns any of those objects (for example, GET /sheets/{sheetId}, GET sheets/{sheetId}/rows/{rowId}, etc.). When this parameter is included, objects that contain non-default formatting will include a format property. Objects which do not have any non-default format settings applied will exclude this property.

Because the amount of format data in a large sheet can potentially be very large in itself, for bandwidth reasons, format data is represented by a compact format descriptor string. The format descriptor takes the form of a comma-separated list of numeric values. These values represent indexes into pre-defined format lookup tables which can be retrieved using the GET /serverinfo operation.

Row & Column Format

Setting the format of a row or column through the API simply sets the baseline format for new cells in that row or column. It does not affect existing cells.

The equivalent API action for what happens when you highlight a column or row in the Smartsheet web app and set a format (e.g. bold) would be to update the format of a column or row (via PUT /sheets/{sheetId}/rows/{rowId} or PUT /sheets/{sheetId}/columns/{columnId}), and update the format for every cell in that row or column. All of the cells in a row can be updated in one operation (PUT /sheets/{sheetId}/rows/{rowId}), but there is currently no way to update all of the cells in a column in one operation. This will be addressed in a future version of the API.

Format Descriptor

The format descriptor contains 16 comma-separated numeric indexes. Each index represents a format style whose value can be found in one of the lookup tables in the FormatTables object.

Format Descriptor Element # Format Style FormatTables Lookup Table Property
0 Font Family fontFamily
1 Font size fontSize
2 Bold bold
3 Italic italic
4 Underline underline
5 Strikethrough strikethrough
6 Horizontal alignment horizontalAlign
7 Vertical alignment verticalAlign
8 Text color color
9 Background color color
10 Taskbar color color
11 Currency currency
12 Decimal count decimalCount
13 Thousands separator thousandsSeparator
14 Number format numberFormat
15 Text wrap textWrap

FormatTables Object

The FormatTables object is retrieved via the GET /serverinfo operation and contains all of the lookup tables that the Format Descriptor indexes refer to, as well as a property called defaults, which is a Format Descriptor that describes which formats the Smartsheet web application displays for unset formats.

defaults string A format descriptor where each element describes the formats the Smartsheet web application displays for format values that have not been set.
fontFamily array of FontFamily objects Font families with additional font information
fontSize array of strings Font sizes in points
bold array of strings Possible values:
  • none
  • on
italic array of strings Possible values:
  • none
  • on
underline array of strings Possible values:
  • none
  • on
strikethrough array of strings Possible values:
  • none
  • on
horizontalAlign array of strings Possible values:
  • none
  • on
verticalAlign array of strings Vertical alignment, possible values:
  • top
  • middle
  • bottom
Note: “default” is the default value, which is equivalent to “top”.
color array of strings Color hex values.

Note: “none” is the default value for all colors. Applications will need to handle this value and use app-defined colors (typically this is Black for text color and White for background color)
currency array of Currency objects Currency codes and symbols
decimalCount array of strings All allowed decimal count values
thousandsSeparator array of strings Possible values:
  • none
  • on
numberFormat array of strings Possible values:
  • none
  • NUMBER
  • CURRENCY
  • PERCENT
textWrap array of strings Possible values:
  • none
  • on

FontFamily Object

name string Name of the font family (e.g. “Arial”)
traits array Platform-independent traits of the font family. One of the following values:
  • serif
  • sans-serif

Currency Object

code string The ISO 4217 currency code (e.g. “EUR”)
symbol string The currency symbol (e.g. “€”)

Deprecations

Smartsheet occasionally deprecates APIs to indicate that those APIs should no longer be used in active development. Deprecated APIs typically remain present and usable for a reasonable period of time following the release in which they were deprecated, but may be removed entirely from a future version of the API. You should never use deprecated APIs in new development, and if you have existing code that uses deprecated APIs, we recommend that you update that code as soon as possible.